SDKの設定

AIショップオファーを使用するために必要なSDKの設定方法を見てみましょう。本ページは次のように構成されています。

必要環境
関連コントローラー、クラス、メソッド
Unity EditorのSDK設定方法:メッセージテンプレートの作成とスクリプトの編集

始める前に

始める前に以下の作業が完了していることを確認してください。

TentuPlayコンソールで新しいアカウントとプロジェクトを作成しましたか？
TentuPlay SDK v2021.4以降をダウンロードしてインストールしましたか？
TentuPlay Unity SDKの設定とデータ収集とアップロードの設定を完了しましたか？

Unityの設定

オファーを正しく表示させるには、Unity Editorとスクリプト作業の両方が必要となります。

Unity Editor で Assets/TentuPlay/TPPersonalizedOfferTemplates にある TPPersonalizedOfferController.prefab のパスを確認します。 TPPersonalizedOfferController.prefab のコンポーネントに TPPersonalizedOfferController.cs スクリプトが含まれています。
TPPersonalizedOfferControllerゲームオブジェクトをSceneに追加します。

下記のサンプルコードのようにtpPersonalizedOfferController` GameObjectパラメータの値を使い、ShowOfferById またはShowLatestOfferを呼び出します。

サンプルコード

public void ShowPersonalizedOffer()
    {
        TPPersonalizedOffer myTPOffer = new TPPersonalizedOffer();
        StartCoroutine(
            myTPOffer.ShowOfferById(tpPersonalizedOfferController, player_uuid, "en", offer_id, (response => { })));
    }

詳しいサンプルはAssets/ShingGoongDemo/Scripts/TentuplayRelated/TentuPlayCRMPlayerController.csとAssets/ShingGoongDemo/Scripts/TentuplayRelated/MailBoxOpen_offer.csをご覧ください。

これで指定した条件下でサンプルオファーがゲーム画面に表示されるようになります。

AIショップオファーがメールボックスに届いた場合の例

AIショップオファーがゲーム画面に表示された場合の例

カスタムオファーとAIショップオファーはOfferInfo.offerTypeで区別されます。

オファーの設定

AIショップオファーを正しく動作させるにはUnity Editorでテンプレートを設定し、必要に応じてスクリプトも変更する必要があります。

メッセージテンプレートの作成

ShowOfferByIdまたはShowLatestOfferが呼び出されると、Scene上のTPPersonalizedOfferController（TPPersonalizedOfferController.ShowOffer）のチャイルドとしてTentuPlayAIOfferが作成されます。

TentuPlayコンソールで指定した画像がOfferImageのTexture/Raw Imageになります。

TPPersonalizedOfferControllerがチャイルドとしてTentuplayAIOffer作成された場合の例

基本テンプレートとして作成されたサンプルメッセージは以下の通りです。

TentuPlay SDKに含まれるサンプルメッセージのテンプレート

この基本テンプレートをベースに必要なテンプレートを作成することができます。

TentuPlayAIOfferのサブコンポーネント（例えばBackgroundImage、Title など）を探します。

TentuPlayAIOfferのチャイルド

ゲームに合わせてテンプレートを編集します。以下の表にはテンプレートを構成する要素と変更可能性や説明が書かれています。

コンポーネント変更可能変更不可備考

コンポーネント	変更可能	変更不可	備考
BackgroundImage	Rect Transformコンポーネントの内容	Raw Imageコンポーネント	TentuPlayコンソールで指定した画像がRaw Imageとして使われる。
Title	Rect Transform, Textコンポーネントの内容	Text ComponentのText	コンソールで指定したメッセージでText ComponentのTextが上書きされる。
Message	Rect Transform, Textコンポーネントの内容	Text ComponentのText	コンソールで指定したメッセージがText ComponentのTextを上書きする。
ProductImage	Rect Transformコンポーネントの内容	Image ComponentのSource Image	`productInfo.sprite`で動的に割り当てられた個人別の画像がImage ComponentのSource Imageを上書きする。
ProductButton	Rect Transformコンポーネントの内容、Image	On Clickイベント	ボタンをクリックすると、（On Click）イベントは`GoToOfferEvent`を使用する。
Price	Rect Transform, Textコンポーネントの内容	Text ComponentのText	`productInfo.price`で動的に割り当てられた個人別の値がText ComponentのTextを上書きする。
CloseButton	Rect Transformコンポーネントの内容	On Clickイベント	ボタンをクリックすると（On Click）イベントは`CloseOfferEvent`を使用する。
Toggle	Rect Transformコンポーネントの内容、Image	On Value Changedイベント	ONにすると（On Value Changed）イベントは`CheckDoNotShowToday`を使用する。
ToggleMessage	Rect Transform, Textコンポーネントの内容	Text ComponentのText	コンソールで指定したメッセージでText ComponentのTextが上書きされる。

BackgroundImage

Rect Transformコンポーネントの内容

Raw Imageコンポーネント

TentuPlayコンソールで指定した画像がRaw Imageとして使われる。

Title

Rect Transform, Textコンポーネントの内容

Text ComponentのText

コンソールで指定したメッセージでText ComponentのTextが上書きされる。

Message

Rect Transform, Textコンポーネントの内容

Text ComponentのText

コンソールで指定したメッセージがText ComponentのTextを上書きする。

ProductImage

Rect Transformコンポーネントの内容

Image ComponentのSource Image

productInfo.spriteで動的に割り当てられた個人別の画像がImage ComponentのSource Imageを上書きする。

ProductButton

Rect Transformコンポーネントの内容、Image

On Clickイベント

ボタンをクリックすると、（On Click）イベントはGoToOfferEventを使用する。

Price

Rect Transform, Textコンポーネントの内容

Text ComponentのText

productInfo.priceで動的に割り当てられた個人別の値がText ComponentのTextを上書きする。

CloseButton

Rect Transformコンポーネントの内容

On Clickイベント

ボタンをクリックすると（On Click）イベントはCloseOfferEventを使用する。

Toggle

Rect Transformコンポーネントの内容、Image

On Value Changedイベント

ONにすると（On Value Changed）イベントはCheckDoNotShowTodayを使用する。

ToggleMessage

Rect Transform, Textコンポーネントの内容

Text ComponentのText

コンソールで指定したメッセージでText ComponentのTextが上書きされる。

ここで設定したメッセージテンプレートはAIショップから送られるすべてのメッセージに適用されます。

コードの編集

ゲーム内でAIショップのメッセージを表示するためにスクリプトを編集しましょう。

スクリプトの場所

TentuPlayAIOffer.prefabのコンポーネントであるTentuPlayAIOffer.csファイルの場所を探します。
- ファイルのパス: Assets/TentuPlay/TPPersonalizedOfferTemplates/TentuPlayAIoffer.cs
  
  Unity内TentuPlayAIOffer.csのパス
TentuPlayAIoffer.csファイル内の PlaceOffer() メソッドを編集します。詳しくは次のセクションで説明します。

PlaceOfferの編集

PlaceOffer()はAIショップのメッセージが画面に表示される前に実行されるメソッドです。このメソッドはTentuPlay AIによって勧められた商品をAIショップのメッセージに表示されるために、予めおすすめ商品に関する情報を取得します。

まず、product_index またはpurchasable_slugを利用して以下の項目を取得するためのゲーム内ロジックが必要です。

sprite: AIショップによるおすすめ商品の画像
price: AIショップによるおすすめ商品の価格
purchase_link: AIショップによるおすすめ商品の購入、または商品に移動するためのリンク
store: アプリストアの名称（データ型: string）

プレイヤーのstore文字列を取得します。

string store = "ios";

storeの文字列は区別可能なアプリストア名であれば何でも（例：android、ios、appstore、playstore）結構ですが、TentuPlayコンソールでアップロードしたCSVファイルの「store」カラムと一致させる必要があります。

store stringを使用するGetRecommendedProductはおすすめ商品の中からプレイヤーのストアに合った商品を生成します。
デモゲームではstoreの既定値は"ios"になっています。

TentuPlay AIのおすすめ商品をユーザーが購入できるように、おすすめ商品のpurchase_linkを取得する必要があります。
- もしTentuPlayコンソール＞ AI In-Game Shop ＞ AI Store運営 ＞ 設定と管理 ＞ 情報のアップロードでアップロードしたCSVファイルの「purchase_link」カラムにアクションリンクを指定した場合、TentuPlay SDKの GetRecommendedProduct メソッドと recommendedProduct クラスを利用しておすすめ商品のpurchase_linkを以下のように取得することができます。
  purchase_link = recommendedProduct.purchase_link;
- CSVファイルにpurchase_linkのアクションリンクを指定しなかった場合、以下のサンプルのようにおすすめ商品の product_index またはpurchasable_slugを利用しておすすめ商品のpurchase_linkを取得する必要があります。
  purchase_link = getProductUrl(purchasable_slug); // purchase_linkを取得するためのカスタムメソッド

TentuPlay AIによるおすすめ商品の画像であるspriteと価格情報であるpriceを以下のように product_index またはpurchasable_slugを利用して取得する必要があります。

ProductInfo productInfo = GetProductInfoDemo(purchasable_slug); // sprite, price(string)を取得するためのカスタムメソッド
Sprite sprite = productInfo.sprite;
string price =productInfo.price;

送信する前にAIショップから送られるメッセージがプレイヤーに正しく表示されるかを検証します。

例えばAIショップによるおすすめ商品に購入回数の制限がかかっている場合、プレイヤーがその商品を購入できる状態かどうかを検証する必要があります。プレイヤーが既におすすめ商品の購入回数上限に達し、これ以上購入できない場合は-1を返してメッセージがプレイヤーに表示されないようにします。サンプルは以下の通りです。

一般的にゲーム側ではメッセージを送信する前に内部検証を行うロジックを搭載しているため、ゲームごとにメッセージを送信する前にAIショップにも内部検証ロジックを適用することをおすすめします。

bool val = validateproduct(player_id, product_index); //内部検証のためのカスタムメソッド
if (!val)
return -1;

上記のステップでエラーが発生した場合は-1を返してメッセージがプレイヤーに表示されないようにしてください。

詳細なコードはTentuPlayAIOffer.csをご覧ください。

AIショップメッセージの成果データ収集

AIショップメッセージが送られると、メッセージを受信したユーザーの行動（例：Open、Dismiss、Interact）に応じた成果データを受信します。この成果データからは送信したメッセージと受信者に関する貴重な情報を得ることができ、（例：どのメッセージがプレイヤーに対して効果があったか？誰がメッセージに敏感に反応したか？）メッセージ本文とデザインの改善点を見つけることができるため、AIオファーに対する成果データを正しく収集するように設定することは重要です。

基本的にAIショップメッセージの成果データを集めるための操作は特に必要ありません。しかし、もし TentuPlayAIOffer.cs で TPStashEvent() コードを変更、または変更したかどうかが不明な場合は TentuPlayAIOffer.cs の PlaceOffer() を次のようにユーザーの行動に応じて異なるメソッドを呼び出すようにしておく必要があります。

メッセージを開くときに呼び出すメソッド

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) =>
        {
        });

メッセージを閉じるときに呼び出すメソッド（TentuPlayOffer.CloseOfferEvent()と同じ）

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);

メッセージ内のボタンをクリックして次のステップに進むときに呼び出すメソッド（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);

全体的にpurchasable_slugがプレイヤーのおすすめ商品として指定されているかを確認してください。

«概要

商品の登録»

SDKの設定

始める前に

関連コントローラー、クラス、メソッドの紹介

Unityの設定

オファーの設定

メッセージテンプレートの作成

コードの編集

スクリプトの場所

PlaceOfferの編集