Set up SDK
This page gives information about how to set up TentuPlay SDK to make an AI in-game shop offer work. You will learn the following:
-
The prerequisites that are required
-
Controllers, classes, and methods that are applicable
-
How to configure SDK in Unity editor including message template cration and script editing
Prerequisites
This page assumes that you are finished with the following:
-
You have created a TentuPlay account and a project in console
-
You have downloaded and installed TentuPlay SDK v2021.4 or later
-
You have completed common TentuPlay Unity SDK setup and configuration for data collection and upload
Controller, class, and methods in use
When ShowOfferById
or ShowLatestOffer
is called, TPPersonalizedOffeController will dynamically retrieve offers by player (namely, player_uuid
) and show them on Scene.
-
ShowOfferById
andShowLatestOffer
are methods of theTPPersonalizedOffer
class -
TPPersonalizedOffer
is a class for displaying TentuPlay Personalized Offers and AI In-Game Shop offers
These components (namely, controller, class, and methods) are used commonly by both personalized offers and AI in-game shop offers. |
Set up Unity
To make an offer appear correctly, you first need to work on both Unity editor and your script.
-
Locate TPPersonalizedOfferController.prefab in Assets/TentuPlay/TPPersonalizedOfferTemplates in Unity editor. It contains its script (TPPersonalizedOfferController.cs) as a component.
-
Add TPPersonalizedOfferController game object to Scene.
-
Call
ShowOfferById
orShowLatestOffer
by usingtpPersonalizedOfferController
GameObject parameter value as shown in the code example.Code examplepublic void ShowPersonalizedOffer() { TPPersonalizedOffer myTPOffer = new TPPersonalizedOffer(); StartCoroutine( myTPOffer.ShowOfferById(tpPersonalizedOfferController, player_uuid, "en", offer_id, (response => { }))); }
For more examples, check out Assets/ShingGoongDemo/Scripts/TentuplayRelated/TentuPlayCRMPlayerController.cs and Assets/ShingGoongDemo/Scripts/TentuplayRelated/MailBoxOpen_offer.cs.
-
Now, an example offer appears on on the game screen when it is meant to be shown.
AI in-game shop offer on mail boxAI in-game shop offer message when opened
The OfferInfo.offerType is the attribute that differentiates between personalized offers and AI in-game shop offers |
Set up an offer
To make an AI in-game shop offer work correctly, you need to configure a template in Unity editor and modify the script as neccessary.
Create a message template
When ShowOfferById
or ShowLatestOffer
is called, TentuPlayAIOffer is generated within the Scene as a child of TPPersonalizedOfferController (TPPersonalizedOfferController.ShowOffer
).
The image entered via the console becomes a Texture/Raw Image of OfferImage. |
At first, you can see the following sample message with default template.
You can use this default template as a starting point to create your own message template.
-
Locate TentuPlayAIOffer's subordinate components (for example, BackgroundImage, Title, and so on).
TentuPlayAIOffer’s child -
Edit them to tailor the template to your game by using the following table that shows you what is allowed to modify and what is not on each child.
Name Editable Uneditable Note BackgroundImage
Rect Transform component’s content
Raw Image component
The image selected in the console is used as Raw Image
Title
Rect Transform, Text component’s content
Text Component’s Text
The text configured in the console overwrites Text Component’s Text
Message
Rect Transform, Text component’s content
Text Component’s Text
The text configured in the console overwrites Text Component’s Text
ProductImage
Rect Transform component’s content
Image Component’s Source Image
The personalized image that is assigned dynamically using
productInfo.sprite
overwrites Image Component’s Source ImageProductButton
Rect Transform component’s content, image
On Click event
When a button is clicked (On Click), the event
GoToOfferEvent
is usedPrice
Rect Transform, Text component’s content
Text Component’s Text
The personalized value that is assigned dynamically using
productInfo.price
overwrites Text Component’s TextCloseButton
Rect Transform component’s content
On Click event
When a button is clicked (On Click), the event
CloseOfferEvent
is usedToggle
Rect Transform component’s content, Image
On Value Changed event
When the toggle is checked (On Value Changed), the event
CheckDoNotShowToday
is usedToggleMessage
Rect Transform, Text component’s content
Text Component’s Text
The text configured in the console overwrites Text Component’s Text
The messages templates which are edited here are applied to all messages sent from the AI in-game shop. |
Edit code
Edit the script so that the AI in-game shop messages can be shown in-game.
Find the script
-
Locate TentuPlayAIOffer.cs that is a component of TentuPlayAIOffer.prefab:
-
File path: Assets/TentuPlay/TPPersonalizedOfferTemplates/TentuPlayAIoffer.cs
TentuPlayAIOffer.cs location within Unity
-
-
Edit the
PlaceOffer()
method in TentuPlayAIoffer.cs as shown in the next section.
Edit PlaceOffer
PlaceOffer()
operates before the AI in-game shop message is shown on screen. It retrieves the recommended product and related information before
an AI in-Game shop message is generated and shown.
Before you begin, make sure that you have implemented the internal logic within your game to retrieve the following information by using
|
-
Retrieve the players' store string.
string store = "ios";
The store string must be identical to that of the 'store' column in the csv file uploaded through TentuPlay console while it can be any name as long as you can identify it as an app store name (for example, android, ios, appstore, playstore)
-
The
GetRecommendedProduct
by using the store string parses the products that matches the player’s store from the recommended products. -
The default value of store is "ios" in the demo game.
-
-
Retrieve the purchase_link of the product that TentuPlay AI recommends through one of the following:
-
If the csv file uploaded on the TentuPlay console > AI-In Game Shop > Shop Operation > Setting/Management > Upload Information tab contains action links in the 'purchase_link' column, the TentuPlay SDK can retrieve the recommended product’s purchase_link via the
GetRecommendedProduct
method and therecommendedProduct
class as shown below:purchase_link = recommendedProduct.purchase_link;
-
If action links are not given in the purchase_link column in the csv file, the recommended item’s purchase_link needs to be retrieved via the product’s
product_index
orpurchasable_slug
as shown below:purchase_link = getProductUrl(purchasable_slug); // a custom method to retrieve a product's purchase_link
-
-
Retrieve the sprite and price of the product recommended by TentuPlay’s AI using the product’s
product_index
orpurchasable_slug
as shown below:ProductInfo productInfo = GetProductInfoDemo(purchasable_slug); // a custom method to retrieve a product's Sprite, price(string) Sprite sprite = productInfo.sprite; string price =productInfo.price;
-
Validate the messages to be sent from the AI in-Game shop before sending.
For example, if a recommended product has any purchase limit, be sure to check first whether a player is allowed to purchase the product. If the player has already reached the purchase limit of the recommended product, your code must return -1 and does not show a message to the player as shown below:
Given that most game developers have an internal logic to check a message’s validity before sending, we recommend that you apply this logic to messages being sent by the AI in-game Shop.
bool val = validateproduct(player_id, product_index); // a custom method to retrieve a product's validity if (!val) return -1;
If an error occurs during the steps, make sure that it returns -1 lest any message should appear on screen. |
For more code examples, please refer to TentuPlayAIOffer.cs. |
- To get the performance data of AI offers correctly
-
After you send the AI in-game Shop messages, you will get the performance data in return by the action that a user takes on them such as
Open
,Dismiss
,orInteract
. It gives the valuable information about the delivered messages (for example, what type of messages work more efficiently for players) and the recipients (for example, the persons who respond to the messages positively and how they interact with them), and offers insights about how to improve the AI offers in terms of texts and graphic interfaces. Thus, it is important to ensure that the achievement data can be retrieved correctly from AI offers you sent.By default, you don’t have to do any further steps to make it work unless you either modify or delete the associated code blocks of
TPStashEvent()
in TentuPlayAIOffer.cs. If you are not sure, make sure that you invoke all of the following methods correctly withinPlaceOffer()
in TentuPlayAIOffer.cs.The methods to be called when a message is openedTPStashEvent 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) => { });
The methods to be called when a message is closed (which is the same as those ofTentuPlayAIOffer.OnCloseOfferEvent()
)int r = new TPStashEvent().StashOfferEvent( player_uuid: thisPlayerUUID, offer_id: thisOffer.offer_id, message_status: messageStatus.Dismiss, //Dismiss! message_detail: purchasable_slug); new TPUploadData().UploadData(toCheckInterval: false);
The methods to be called when a button is clicked to continue on a message (which is the same as those ofTentuPlayAIOffer.OnGoToOfferEvent()
)int r = new TPStashEvent().StashOfferEvent( player_uuid: thisPlayerUUID, offer_id: thisOffer.offer_id, message_status: messageStatus.Interact, //Interact! message_detail: purchasable_slug); new TPUploadData().UploadData(toCheckInterval: false);
Make sure that you assign the name of recommended product for the player to
purchasable_slug
. It goes for all of the methods.