Work on offers
An offer in TentuPlay is a type of recommendation system to improve users' efficiency and experience in the game. If you want to use the offer system, there are two main tasks to be done that are getting offer data and updating reaction to offer message. Let’s learn how to do the tasks
The explanations on this section are based on the following assumptions:
|
Retrieve offer data
Once you complete the data upload pertaining to user actions, TentuPlay server periodically analyzes them and stores the processed data to be consumed at request for analytics and offers. The first thing you need to do is to retrieve valid offer data that TentuPlay server retains. You then can construct and create an offer message by using the offer data from the server.
Request
GET https://api.tentuplay.io/v2021.4/unity/offers HTTP/1.1
Content-Type:application/json
Response
Success
HTTP/1.1 200 OK
Content-Type:application/json
{
"status": 200,
"reason": "OK",
"data": [
{
"offer_id": 2,
"player_slug": "TentuPlayer",
"offer":
"{
\"offer_type\": \"ai\",
\"is_offer_active\": true,
\"recommendations\": [
{
\"store\": \"ios\",
\"product_list\": [
{
\"end_datetime\": null,
\"product_index\": \"00000\",
\"purchase_link\": \"https://tentuplay.io/\",
\"start_datetime\": null,
\"purchasable_slug\": \"BombBow\"
}
]
}
],
\"display_parameters\":
{
\"en\":
{
\"title\": \"A Special Recommendation For EXPLOSIVE Growth!\",
\"message\": \"Congratulations on reaching <color=#FFD84F>explosive growth!</color>\\n In 3 days you earned 1000 coins,\\n and reached level 7!\\n If you buy the following product, you can grow more efficiently.\",
\"background_url\": \"https://tentuplay-static.s3.ap-northeast-2.amazonaws.com/black_background.png\",
\"toggle_message\": \"Don't Show Again Today\"
},
\"ko\":
{
\"title\": \"폭풍성장 플레이어를 위한 특별한 정보!\",
\"message\": \"<color=#FFD84F>폭풍성장</color> 등급 달성을 축하합니다.\\n 3일 동안 코인을 1000만큼 획득하고,\\n 7레벨 성장하셨습니다!\\n 다음의 상품을 구매하면 효율을 더욱 높일 수 있습니다.\",
\"background_url\": \"https://tentuplay-static.s3.ap-northeast-2.amazonaws.com/black_background.png\",
\"toggle_message\": \"오늘 다시보지 않기\"
}
}
}",
"create_datetime": "2021-11-08 06:36:07",
"valid_until": null,
"valid_for": null,
"valid_open_count": null,
"first_opened_at": null,
"is_offer_active": 1
},
{
"offer_id": 1,
"player_slug": "TentuPlayer",
"offer":
"{
\"price\": 99.99,
\"message\":
{
\"en\":
{
\"url\": \"https://tentuplay.io/en/\",
\"image\": \"https://tentuplay-static.s3.ap-northeast-2.amazonaws.com/offer_demo_image_landscape.png\",
\"title\": \"english campaign\"
},
\"ko\":
{
\"url\": \"https://tentuplay.io/ko/\",
\"image\": \"https://tentuplay-static.s3.ap-northeast-2.amazonaws.com/offer_demo_image_landscape.png\",
\"title\": \"한글 캠페인\"
}
},
\"product_id\": null,
\"product_name\": null,
\"discount_rate\": 10,
\"discount_price\": 89.99,
\"message_layout\": \"h\"
}",
"create_datetime": "2021-11-08 06:36:07",
"valid_until": null,
"valid_for": null,
"valid_open_count": null,
"first_opened_at": null,
"is_offer_active": 1
}
]
}
Construct offers
Once you get a response to your offer request, you need to check the validity of offer data first and then generate offer message for its recipient. The following explanations are based on the sample response body in the preceding section.
Check offer’s validity
Examine the elements in the following table to make sure that you can use the offer correctly:
Components | Description | Note | |
---|---|---|---|
Common |
|
|
|
|
Use the offer only when |
||
|
It shows when the offer was opened for the first time. The |
||
|
Calculate the offer’s expiry date by using them |
||
|
It denotes when the offer was created in UTC |
||
|
|
Check whether the product is still on sale by using them |
The values for AI offers are created only when you upload the product information file. |
|
Check whether the player is allowed to purchase the product by one or more of them |
||
|
Construct the offer that runs correctly on player’s device OS on the basis of |
Build offers
The next step is to parse the corresponding body contents and put them into the offer’s graphical user interface (GUI) so that users can consume the offer by interacting with it.
This step assumes that you already have contructed a GUI for offer presentation that consists of a message window, text fields, and other control elements (for example, buttons and check boxes). Note that there are basic UI templates available in Unity SDK for creating an offer message (AI offer template, Personalized offer template).
Build AI in-game shop offers
-
Arrange the display contents (
title
,messeage
,background_url
, andtoggle_message
underdisplay_parameters
) on the UI by language. -
Add the product information (
product_index
,purchasable_slug
, andpurchase_link
underrecommendations
) to offers so that users can purchase the recommended products presented on offer message. (Steps on Unity SDK described)
Update offer state
If something happens to an offer, you need to reflect the change in the offer’s state to the server. An offer state update is required for one of the following events:
-
When you retrieve offers for users from the TentuPlay server
-
When the users interact with the offers such as open, close, or proceed
When an offer is exposed
The first step is to let the server know that the offer reaches you successfully on your request. This state is called "impress".
Request
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/json
Headers
Name | Value | Type | Required | Default |
---|---|---|---|---|
TPAuthMode |
|
string |
required |
null |
TPClientKey |
string |
required |
null |
Body
{
"players_offers": [
{
"player_slug": "TentuPlayer",
"offer_id": 999,
"message_status": "impress",
"message_detail": "this_purchasable_slug",
"event_timestamp": 1647504609
}
],
...
}
Name | Description | Type | Required | Notes |
---|---|---|---|---|
player_slug |
The player’s unique ID |
string |
required |
In Unity SDK, it is |
offer_id |
Unique ID assigned to the offer |
int |
required |
|
message_status |
Events happened to the offer
|
string |
required |
|
message_detail |
Unique ID of in-game contents related to an advertisement in an offer (for example, advertised in-game item, DLC product, and in-game gift card) |
string |
optional |
|
event_timestamp |
Unix time by UTC |
int |
required |
When an offer is consumed
When an offer message is ready, the message will be sent to target users under predefined conditions. If the offer message is delivered to the users successfully, they can give a reaction to it like opening or just ignoring. This kind of user interaction will change the message status and you need to reflect the change, if applicable, to the same of the server. When the resource state of offer message is updated, the metric for the offer accomplishment will be updated as well.
Update when an offer is first opened
When the offer is opened by the user for the first time, you need to inform the server of this event including its timestamp. This will attach a time value to the first_opened_at
attribute of the offer in the server. It is usually used to calculate the offer’s validity period.
POST https://api.tentuplay.io/v2021.4/unity/offers HTTP/1.1
Content-Type:application/json
Name | Value | Type | Required | Note |
---|---|---|---|---|
TPAuthMode |
|
string |
required |
|
TPClientKey |
string |
required |
||
TPOfferId |
Offer ID |
int |
required |
|
TPPlayerId |
Player ID |
string |
required |
|
TPOpenedAt |
The timestamp when the offer is opened for the first time |
string |
required |
Example: |
If you get an offer that has never been opened (namely, |
Update when a user consumes an offer
There are three types of user interactions with an offer in TentuPlay that can be illustrated by message_status
.
-
open
: The player opened the offer. -
dismiss
: The player clicked the close button on the offer UI. -
interact
: The player took the next step on the offer by clicking an associated button such as Purchase.
POST https://api.tentuplay.io/v2021.4/unity/logs HTTP/1.1
Content-Type:application/json
Name | Value | Type | Required | Default |
---|---|---|---|---|
TPAuthMode |
|
string |
required |
null |
TPClientKey |
string |
required |
null |
Body example
{
"players_offers": [
{
"player_slug": "TentuPlayer",
"offer_id": 999,
"message_status": "open",
"message_detail": "this_purchasable_slug",
"event_timestamp": 1647504609
}
],
...
}
{
"players_offers": [
{
"player_slug": "TentuPlayer",
"offer_id": 999,
"message_status": "dismiss",
"message_detail": "this_purchasable_slug",
"event_timestamp": 1647504609
}
],
...
}
{
"players_offers": [
{
"player_slug": "TentuPlayer",
"offer_id": 999,
"message_status": "interact",
"message_detail": "this_purchasable_slug",
"event_timestamp": 1647504609
}
],
...
}
Sample code for offer state update
TPStashEvent myStashEvent = new TPStashEvent();
myStashEvent.StashOfferEvent(
player_uuid: player_id, offer_id: thisOffer.offer_id,
message_status: messageStatus.Open, message_detail: purchasable_slug);
myPerOffer.OfferOpened(thisOffer.offer_id, (response) =>
{
});
int r = new TPStashEvent().StashOfferEvent(
player_uuid: thisPlayerUUID, offer_id: thisOffer.offer_id, message_status: messageStatus.Dismiss,
message_detail: purchasable_slug);
new TPUploadData().UploadData(toCheckInterval: false);
int r = new TPStashEvent().StashOfferEvent(
player_uuid: thisPlayerUUID, offer_id: thisOffer.offer_id, message_status: messageStatus.Interact,
message_detail: purchasable_slug);
new TPUploadData().UploadData(toCheckInterval: false);