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.
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
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/json
POST https://api.tentuplay.io/v2021.4/unity/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 |
|
string |
required |
null |
TPClientKey |
string |
required |
null |
Body
{
"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
}
]
}
Name | Description | Type | Required | Notes | ||
---|---|---|---|---|---|---|
players_join |
Uploading the data included in |
|||||
player_slug |
The player’s unique ID |
string |
required |
In Unity SDK, it is |
||
device_unique_id |
string |
required |
||||
device_info |
The information about client device |
string |
required |
Format: |
||
region |
Two-letter country code |
string |
required |
|||
is_tp_debug_mode |
Whether the SDK is in debug mode |
int |
required |
Valid values: |
||
event_timestamp |
Unix time by UTC |
int |
required |
|||
players_login |
Uploading the data included in |
|||||
app_version |
The version of the application when the player logs in |
string |
optional |
Default: |
||
sdk_version |
The SDK version |
string |
required |
Current version: |
||
characters_purchases |
Uploading the data included in |
|||||
character_slug |
The unique ID of player’s character
|
string |
required |
In Unity SDK, it is |
||
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.
|
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:
|
Response
Success
HTTP/1.1 200 OK
Content-Type:application/json
{
"status": 200,
"reason": "OK",
"data": {
"default": {},
"cache": {
"cache_players_join": null,
"cache_players_login": null,
"cache_characters_purchases": null
}
}
}
Failure
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 |
|
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: |
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
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/json
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/octet-stream
Headers
Name | Value | Type | Required | Default |
---|---|---|---|---|
TPAuthMode |
|
string |
required |
null |
TPClientKey |
string |
required |
null |
Body
{
"{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. |
{
"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. |