Collect data

Data collection is the process of gathering information on player’s behaviors during game play or product use such as login and currency acquistion. It is achieved at the client side by consuming the correspoding APIs. Collected data is used as a basis of data analysis that leads to the generation of personalized or AI in-game shop offers.

TentuPlay REST upload data en
Collecting data overview

Upload basic data

This page gives you a simplifed version of data upload instruction. It includes three basic user behavioral data only.

Join, Login, and InAppPurchase constitute the basic user actions whose data are being used to produce the core information (also known as Hourglass analysis) about your product such as user activity, attendance frequency, number of buyers, revenue, and average login days. You can use these behavioral data to evaluate the activity and marketability not only for your games but also for other software product (for example, web sites).

Request

Request scheme
  • Without data compression

  • With data compression

POST https://api.tentuplay.io/v2021.4/logs HTTP/1.1
Content-Type:application/json
POST https://api.tentuplay.io/v2021.4/logs HTTP/1.1
Content-Type:application/octet-stream

With compression, the data in the request body will be transferred by bytes with UTF8 encoded.

Headers

Name Value Type Required Default

TPAuthMode

api_key_plain

string

required

null

TPClientKey

Client key

string

required

null

Body

Body example
{
  "players_join": [
    {
      "player_slug": "TentuPlayer",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
  "players_login": [
    {
      "player_slug": "TentuPlayer",
      "app_version": null,
      "sdk_version": "2021.4",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
	"characters_purchases": [
	   {
	     "player_slug":"TentuPlayer",
	     "character_slug":"_DUMMY_CHARACTER_ID_",
	     "purchasable_slug":"productSlug",
	     "purchase_quantity":2.0,
	     "purchase_unit_price":2.5,
	     "purchase_total_price":5.0,
	     "purchase_currency_code":"USD",
	     "is_ad_remove":true,
	     "event_timestamp": 1647504609
	   }
   ]
}
Body parameters
Name Description Type Required Notes

players_join

Uploading the data included in players_join is equivalent to calling Join method in Unity SDK

player_slug

The player’s unique ID

string

required

In Unity SDK, it is player_uuid

device_unique_id

The client device’s unique ID

string

required

device_info

The information about client device

string

required

Format: OS || Model name || Device type

region

Two-letter country code

string

required

is_tp_debug_mode

Whether the SDK is in debug mode

int

required

Valid values: 0, 1

event_timestamp

Unix time by UTC

int

required

players_login

Uploading the data included in players_login is equivalent to calling LoginApp method in Unity SDK

app_version

The version of the application when the player logs in

string

optional

Default: null

sdk_version

The SDK version

string

required

Current version: 2021.4

characters_purchases

Uploading the data included in characters_purchases is equivalent to calling InAppPurchase method in Unity SDK

character_slug

The unique ID of player’s character

If there is no character in the game or If you want to use it for the player, not a character, set character_slug to TentuPlayKeyword._DUMMY_CHARACTER_ID_.

string

required

In Unity SDK, it is character_uuid

purchasable_slug

The unique ID of purchased product

string

required

purchase_quantity

The number or amount of purchased products

double

required

purchase_unit_price

The unit price of purchased product

double

required

purchase_total_price

The total price of purchased products

double

required

purchase_currency_code

Three-letter alphabetic code of currency used for the purchase defined by ISO 4217

string

required

is_ad_remove

Whether the purchased item either includes or is related to in-app ad removal

boolean

optional

If there is no data to post in players_join, players_login, or characters_purchases, you can omit the whole objects that have empty fields in the body. For instance, the following request body is allowed.

{
  "players_join": [
    {
      "player_slug": "TentuPlayer",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ]
}

Given that each data object (that is, table) consists of ordered lists, you can put multiple contents of events into an object as shown in the following example:

{
  "characters_purchases": [
    {
      "player_slug":"TentuPlayer",
      "character_slug":"_DUMMY_CHARACTER_ID_",
      "purchasable_slug":"productSlug1",
      "purchase_quantity":2.0,
      "purchase_unit_price":2.5,
      "purchase_total_price":5.0,
      "purchase_currency_code":"USD",
      "is_ad_remove":true,
      "event_timestamp": 1647504609
    },
    {
      "player_slug":"TentuPlayer",
      "character_slug":"_DUMMY_CHARACTER_ID_",
      "purchasable_slug":"productSlug2",
      "purchase_quantity":2.0,
      "purchase_unit_price":2.5,
      "purchase_total_price":5.0,
      "purchase_currency_code":"USD",
      "is_ad_remove":true,
      "event_timestamp": 1647504609
    }
  ]
}

Response

Success

HTTP/1.1 200 OK
Content-Type:application/json
Body example
{
    "status": 200,
    "reason": "OK",
    "data": {
        "default": {},
        "cache": {
            "cache_players_join": null,
            "cache_players_login": null,
			      "cache_characters_purchases": null
        }
    }
}

Failure

Status and error codes

Key

Description

Note

status

reason

403

"Method Not Allowed"

The method is allowed for this operation (not POST, for example)

400

"Missing Headers"

No headers found

400

"Missing TPAuthMode"

No TPAuthMode key found in the header

400

"Invalid TPAuthMode"

Unknown value in TPAuthMode key, not api_key_plain

400

"Missing TPClientKey"

No TPClientKey key found in the header

403

"Invalid TPClientKey"

Invalid value in TPClientKey key

400

"Missing Body"

No body found on request

400

"Missing Content-Type"

No content_type found

400

"Unsupported Content Type"

Invalid content-type

Valid values: application/json, application/octet-stream

Upload full data

This page gives you a full version of data upload instruction. It includes all of user behavioral data available for Tentuplay service.

The other behavioral data than the basic ones are mostly needed to analyze user interactions with in-game items, stages, and characters. It gives additional game performance metrics like playing time of a specific stage. These data, most of all, serve as the ingredients to create personalized offers tailored to their target users or correspoding user segment. Thus, if your product is a game and you want to give players offers to increase retention and revenue, you need to upload the data by the following instruction.

Request

Request scheme
  • Without data compression

  • With data compression

POST https://api.tentuplay.io/v2021.4/logs HTTP/1.1
Content-Type:application/json
POST https://api.tentuplay.io/v2021.4/logs HTTP/1.1
Content-Type:application/octet-stream

Headers

Name Value Type Required Default

TPAuthMode

api_key_plain

string

required

null

TPClientKey

Client key

string

required

null

Body

Request body scheme
{
  "{object name}": [ (1)
    {
      "{attribute name}": "{value}", (2)
      ...
    },
    ...
  ],
  ...
}
1 An object in JSON corresponds to a table in database. All the available objects are listed in Objects for data upload.
2 An attribute in JSON corresponds to a column in database. All the available attributes for every object are listed in Attributes for data upload. For the description of each attribute, see request body parameters in basic data upload and the Parameters section of each method in Unity API reference.
Body example
{
  "players_join": [
    {
      "player_slug": "TentuPlayer",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
  "players_login": [
    {
      "player_slug": "TentuPlayer",
      "app_version": null,
      "sdk_version": "2021.4",
      "device_unique_id": "{device_unique_id}",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    },
    {
      "player_slug": "TentuPlayer",
      "app_version": null,
      "sdk_version": "2021.4",
      "device_unique_id": "99bc8eac57de4b506a4164eef8699b46a37f4f9c",
      "device_info": "{OS version || Model name || Device type}",
      "region": "KR",
      "is_tp_debug_mode": 1,
      "event_timestamp": 1647504609
    }
  ],
  "characters_login": [], (1)
  "characters_purchases": [],
  "characters_ads": [],
  "characters_quests": [],
  "characters_bonuses": [],
  "players_characters_change": [],
  "characters_stats_change": [],
  "characters_custom_ability_change": [],
  "players_stages": [],
  "characters_stages": [],
  "characters_items_infrastructure_play": [],
  "characters_items_consumable_play": [],
  "characters_items_equipment_play": [],
  "characters_items_cosmetic_play": [],
  "characters_skills_play": [],
  "players_characters_get": [
    {
      "player_slug": "TentuPlayer",
      "character_slug": "_DUMMY_CHARACTER_ID_",
      "characterarchetype_slug": "DUMMY_CHARACTER",
      "reference_entity": "join",
      "reference_category_slug": "JOIN",
      "reference_slug": "JOIN",
      "event_timestamp": 1647504609
    }
  ],
  "characters_currencies_get": [],
  "characters_items_infrastructure_get": [],
  "characters_items_token_get": [],
  "characters_items_consumable_get": [],
  "characters_items_material_get": [],
  "characters_items_equipment_get": [],
  "characters_items_cosmetic_get": [],
  "characters_items_randombox_get": [],
  "characters_currencies_use": [],
  "characters_items_equip": [],
  "characters_items_token_use": [],
  "characters_items_consumable_use": [],
  "characters_items_material_use": [],
  "characters_items_randombox_use": [],
  "characters_skills_equip": [],
  "players_characters_dismiss": [],
  "characters_items_dismiss": [],
  "characters_levelup": [],
  "characters_items_levelup": [],
  "characters_skills_levelup": [],
  "characters_currencies_deposit": [],
  "characters_items_deposit": [],
  "characters_currencies_withdraw": [],
  "characters_items_withdraw": []
}
1 If there is no data to post in an object (table), you can leave out the whole object in the body. It suggests you don’t need to put empty objects unlike "characters_login": [], "characters_purchases": [] as shown in the body example.

Response

Success

HTTP/1.1 200 OK
Content-Type:application/json
Body example
{
    "status": 200,
    "reason": "OK",
    "data": {
        "default": {},
        "cache": {
            "cache_players_join": null,
            "cache_players_login": null,
			      "cache_characters_purchases": null
        }
    }
}