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:

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 and ShowLatestOffer are methods of the TPPersonalizedOffer 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.

  1. Locate TPPersonalizedOfferController.prefab in Assets/TentuPlay/TPPersonalizedOfferTemplates in Unity editor. It contains its script (TPPersonalizedOfferController.cs) as a component.

    image (8)
    image (9)
  2. Add TPPersonalizedOfferController game object to Scene.

    image (10)
  3. Call ShowOfferById or ShowLatestOffer by using tpPersonalizedOfferController GameObject parameter value as shown in the code example.

    Code example
    public 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.

  4. Now, an example offer appears on on the game screen when it is meant to be shown.

    image (20)
    AI in-game shop offer on mail box
    image (21)
    AI 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 ShowLatestOfferis 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.

306
TentuPlayAIOffer created as a child of TPPersonalizedOfferController

At first, you can see the following sample message with default template.

image (24)
Default message templates included within the TENTUPLAY SDK

You can use this default template as a starting point to create your own message template.

  1. Locate TentuPlayAIOffer's subordinate components (for example, BackgroundImage, Title, and so on).

    image (23)
    TentuPlayAIOffer’s child
  2. 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 Image

    ProductButton

    Rect Transform component’s content, image

    On Click event

    When a button is clicked (On Click), the event GoToOfferEvent is used

    Price

    Rect Transform, Text component’s content

    Text Component’s Text

    The personalized value that is assigned dynamically using productInfo.price overwrites Text Component’s Text

    CloseButton

    Rect Transform component’s content

    On Click event

    When a button is clicked (On Click), the event CloseOfferEvent is used

    Toggle

    Rect Transform component’s content, Image

    On Value Changed event

    When the toggle is checked (On Value Changed), the event CheckDoNotShowToday is used

    ToggleMessage

    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

  1. Locate TentuPlayAIOffer.cs that is a component of TentuPlayAIOffer.prefab:

    • File path: Assets/TentuPlay/TPPersonalizedOfferTemplates/TentuPlayAIoffer.cs

      image (25)
      TentuPlayAIOffer.cs location within Unity
  2. 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 product_index or purchasable_slug.

  • sprite: The image of the product recommended by the AI in-game shop

  • price: The price of the product recommended by the AI in-game shop

  • purchase_link: A link to a purchase page of the product or a link to the product page recommended by the AI in-game shop

  • store: An alias of app store (type: string)

  1. 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.

  2. 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 the recommendedProduct 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 or purchasable_slug as shown below:

      purchase_link = getProductUrl(purchasable_slug); // a custom method to retrieve a product's purchase_link
  3. Retrieve the sprite and price of the product recommended by TentuPlay’s AI using the product’s product_index or purchasable_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;
  4. 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,or Interact. 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 within PlaceOffer() in TentuPlayAIOffer.cs.

The methods to be called when a message is opened
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) =>
        {
        });
The methods to be called when a message is closed (which is the same as those of TentuPlayAIOffer.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 of TentuPlayAIOffer.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.