Unity SDK

Unity SDK実装ガイド

• 過去のバージョン履歴については、こちらのリリースノートを御覧ください。
• iOSおよびAndroidのドキュメントをご確認いただき、ビルドに適切なプラットフォーム設定を適用ください。
• ご質問がある方は、support@tenjin.comまでお問い合わせください。
  
  

目次

• SDK実装手順
  • Google Play
  • Amazonストア
  • その他のAndroidストア
    • MSA OAID
    • Huawei OAID
  • 難読化設定
  • SDK初期化
  • アプリストア設定
  • ATTrackingManager (iOS)
    • ATT許可プロンプトの表示
      • ユーザー追跡の説明の設定
  • SKAdNetworkとコンバージョンバリュー
  • SKAdNetwork iOS 15+ Postbacks
  • GDPR対応
  • アプリ内課金イベント
    • iOSレシート検証
    • Androidレシート検証
  • カスタムイベント
  • サーバ間インテグレーション
  • アプリサブバージョン
  • Live Opsキャンペーン
  • カスタマーユーザID
  • イベントのリトライ/キャッシュ
• インプレッションレベル広告収益
• テスト

SDK実装手順

1. こちらより最新のUnity SDKをダウンロードします。
2. お客様のプロジェクト上のAssets -> Import Package上で、TenjinUnityPackage.unitypackageをインポートします。
3. デフォルトでは、Google PlayサービスのAARファイルがSDK内に含まれています。Google Playサービスが必要なければ、下記のAARファイルを削除して下さい。

 /Assets/Plugins/Android/play-services-*.aar
 /Assets/Plugins/Android/installreferrer-*.aar

デモプロジェクトtenjin-unity-sdk-demoは、tenjin-unity-sdkの実装サンプルです。

Googleプレイストア

デフォルトでは、unspecifiedがデフォルトのAppStoreです。アプリをGooglePlayストアで配布する場合は、アプリストアの値をgoogleplayに更新します。
App StoreTypeの値を googleplayに設定します。

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.googleplay);

Amazonストア

デフォルトでは、unspecifiedがデフォルトのAppStoreです。アプリをAmazonストアで配布する場合は、アプリストアの値をamazonに更新します。

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.amazon);

他アンドロイドアプリストア

TenjinはAndroidのOAIDを使用したAndroidアプリストアのトラッキングをサポートしています。OAIDライブラリを実装した場合のオプションは下記の通りです。Google Play以外のアプリを開発する場合は、OAIDライブラリの実装が必須です。

MSA OAID

MSA OAIDは、MSA (Mobile Security Alliance)が提供する、中国で製造されるデバイスで取得可能な広告IDです。MSAライブラリを実装する場合は, oaid_sdk_1.0.25.aarをダウンロードします。oaid_sdk_1.0.25.aarファイルを、プロジェクトのAndroidライブラリディレクトリに配置してください。:/Assets/Plugins/Android

次に、下記の通りアプリストアタイプの値をotherに設定します。

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.other);

Huawei OAID

中国以外では、Huaweiによって提供されるOAIDを取得することが可能です。Huawei OAIDライブラリを実装するには、次のHuawei AARファイル: huawei-ads-identifier.aarをダウンロードしてください。

アプリギャラリーにアプリを登録する場合は、Huaweiのインストールリファラファイル：huawei-ads-installreferrer.aarをダウンロードしてください。それらのHuaweiファイルを、プロジェクトのAndroidライブラリディレクトリに配置してください。:/Assets/Plugins/Android

次に、下記の通りアプリストアタイプの値をotherに設定します。

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.other);

難読化設定

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected java.lang.Object[][] getContents();
}
-keepattributes *Annotation*

Huaweiのライブラリを使用している場合、下記の設定を行ってください。

-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }

SDK初期化

1. Appsページから SDK_KEY を取得します。注: SDK_KEY はアプリごとに一意です。同じアプリに対して最大3つまでキーを作成できます。

   

2. プロジェクト内の初回のStart()メソッド内で、下記のコードを追加します。また、バックグラウンド復帰時にもセッション情報を送信する場合は、OnApplicationPause()にも追加します。

   using UnityEngine;
   using System.Collections;
   
   public class TenjinExampleScript : MonoBehaviour {
   
     void Start() {
       TenjinConnect();
     }
   
     void OnApplicationPause(bool pauseStatus) {
       if (!pauseStatus) {
         TenjinConnect();
       }
     }
   
     public void TenjinConnect() {
       BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
   
       // Sends install/open event to Tenjin
       instance.Connect();
     }
   }
   

注: このコードは、アプリの初回起動だけでなく、すべての Start()と OnApplicationPause()に実装するようにしてください。推奨事項に従わない場合は、適切なサポートを提供できないか、アカウントが停止される可能性があります。

アプリストア設定

下記の3つのアプリストアのオプションをサポートしています。

1. googleplay
2. amazon
3. other

デフォルトでは, unspecifiedがアプリストアの設定になります。特定のアプリストアにパブリッシュする場合は、アプリストアを適切な値に設定してください。otherのアプリストアはHuaweiアプリギャラリーやその他のアプリストアで使用されます。

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="{{SET_APP_STORE_TYPE_VALUE}}" />

2. SetAppStoreType():

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.{{SET_APP_STORE_TYPE_VALUE}});

ATTrackingManager (iOS)

• iOS 14では、ATTrackingManagerを使用して許可プロンプトを表示し、ユーザをオプトイン/オプトアウトする事が可能です。
• デバイスがトラッキングの許可を行わない場合は、IDFAはゼロとなります。デバイスがトラッキングの許可を行った場合、connect()メソッドを通じてIDFAがサーバ側に送られます。

using UnityEngine;
using System.Collections;
using UnityEngine.iOS;

public class TenjinExampleScript : MonoBehaviour {

    void Start() {
      TenjinConnect();
    }

    void OnApplicationPause(bool pauseStatus) {
      if (!pauseStatus) {
        TenjinConnect();
      }
    }

    public void TenjinConnect() {
      BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

#if UNITY_IOS
      if (new Version(Device.systemVersion).CompareTo(new Version("14.0")) >= 0) {
        // Tenjin wrapper for requestTrackingAuthorization
        instance.RequestTrackingAuthorizationWithCompletionHandler((status) => {
          Debug.Log("===> App Tracking Transparency Authorization Status: " + status);

          // Sends install/open event to Tenjin
          instance.Connect();

        });
      }
      else {
          instance.Connect();
      }
#elif UNITY_ANDROID

      // Sends install/open event to Tenjin
      instance.Connect();

#endif
    }
}

ATT許可プロンプトの表示

AppleのATTガイドラインに準拠するには、ATT許可プロンプトの説明を入力し、アプリケーションへの許可リクエストを実装する必要があります。

注: ゲーム内で広告を配信する前に、許可リクエストを実装する必要があります。

ユーザー追跡の説明の設定

XcodeプロジェクトのInfo.plistファイル内のNSUserTrackingUsageDescriptionキーを使用して説明の内容を設定します。デバイス追跡データの使用許可を要求している理由をユーザーに通知するメッセージを提供する必要があります。

• Xcodeプロジェクトナビゲータで、 Info.plistファイルを開きます。
• プロパティリストエディタの任意のキーの横にある追加ボタン（+）をクリックして、新しいプロパティキーを作成します。
• キー名 NSUserTrackingUsageDescriptionを入力します。
• 文字列値のタイプを選択します。
• 値フィールドにアプリ追跡のメッセージを入力します。いくつかの例が含まれます：
  • お客様のデータを使用して、より優れたパーソナライズされた広告エクスペリエンスを提供します。
  • 使用しているアプリ、使用しているデバイス、使用している国に基づいて、最も興味のあるアプリや製品の広告を表示するようにしています。
  • 私たちは、あなたが使用するアプリに基づいて、あなたにとって最も興味深いアプリや製品の広告を表示しようとします。

注: Appleは、プライバシー関連の機能に直面しているすべてのエンドユーザーの許容可能な使用とメッセージングを定義する特定のアプリストアガイドラインを提供しています。Tenjinは法律上の助言を提供していません。したがって、このページの情報は、お客様のビジネスとプロセスの法的要件、およびそれらに対処する方法を決定するための法的手段の代替ではありません。

SKAdNetworkとコンバージョンバリュー

SKAdNetworkの導入に従って, TenjinではupdatePostbackConversionValue(_:)のラッパーメソッドを用意しています。このメソッドは、該当のSKAdNetworkのメソッドをコールし、コンバージョンバリューをTenjinのサーバに送信します。

updatePostbackConversionValue(_:)の6ビットの値はアプリ内イベントに対応する値で、バイナリ値ではなく0-63の間の整数値である必要があります。これ以外の数値の場合、サーバ側でエラーとなります。

SKAdNetwork 4.0がサポート対象となるiOS 16.1以降で、coarseValue(文字列、可能な引数はlow、medium, high)とlockWindow(真偽値)を更新ポストバックメソッドのパラメーターとして送信できるようになりました。

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String)

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String, lockWindow: Bool)

• SKAdNetwork 4.0に対応したiOSバージョン16.1以降では、このメソッドを何度でも呼び出すことができ、コンバージョンバリューを以前の値よりも低くしたり高くしたりできます。

• 4.0より前のSKAdnetWorkバージョンをサポートする16.1より前のiOSバージョンの場合、このメソッドを呼び出すと、SDKが自動的にiOSバージョンを検出し、conversionValueのみを更新します。

using UnityEngine;
using System.Collections;

public class TenjinExampleScript : MonoBehaviour {

    void Start() {
      TenjinConnect();
    }

    void OnApplicationPause(bool pauseStatus) {
      if (!pauseStatus) {
        TenjinConnect();
      }
    }

    public void TenjinConnect() {
      BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

#if UNITY_IOS

      // Sends install/open event to Tenjin
      instance.Connect();

      // Sets SKAdNetwork Conversion Value
      // You will need to use a value between 0-63 for <YOUR 6 bit value>
      instance.updatePostbackConversionValue(<your 6 bit value>);
      
       // For iOS 16.1+ (SKAN 4.0)
      instance.updatePostbackConversionValue(<your 6 bit value>, "medium");
      instance.updatePostbackConversionValue(<your 6 bit value>, "medium", true);

#elif UNITY_ANDROID

      // Sends install/open event to Tenjin
      instance.Connect();

#endif
    }
}

SKAdNetworkとiOS 15+広告主向けポストバック

SKAdNetworkのポストバックにおいて、Tenjinを送信先に設定するためには、下記をご設定ください。

1. XCodeのプロジェクトナビゲーターで、Info.plistを選択します。
2. プロパティリストエディタ上で、keyのそばの追加ボタン(+)をクリックし、リターンを押下します。
3. NSAdvertisingAttributionReportEndpointをkeyの名称として入力します。
4. Typeのカラムで、ポップアップメニューからStringを選択します。
5. https://tenjin-skan.comを入力します。

これらのステップは、Appleのインストラクション: https://developer.apple.com/documentation/storekit/skadnetwork/configuring_an_advertised_app を基にしています。

GDPR

GDPRへの対応において、Tenjin SDKではデバイス/ユーザのオプトイン, オプトアウトおよび各デバイスパラメータのオプトイン, オプトアウトが可能です。OptOut()メソッドにより、Tenjinにリクエストが送られることはありません。

オプトイン, オプトアウトの具体例:

void Start () {

  BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

  boolean userOptIn = CheckOptInValue();

  if (userOptIn) {
    instance.OptIn();
  }
  else {
    instance.OptOut();
  }

  instance.Connect();
}

boolean CheckOptInValue()
{
  // check opt-in value
  // return true; // if user opted-in
  return false;
}

• 特定のデバイスパラメータをオプトイン,オプトアウトするにはOptInParams() または OptOutParams()メソッドを使用します。

• OptInParams()メソッドにより指定されたパラメータのみを送信します。OptOutParams()メソッドにより、指定されたパラーメータ以外のパラメータを送信します。

• 注意点：Tenjin上で正しくユーザをトラッキングするには、下記のパラメータが必須となります。

  • Android
    • advertising_id
  • iOS
    • developer_device_id

• IMEIまたはOAIDを使用したネットワークでプロモーションを実施する場合は、下記のパラメータが必須となります。

  • imei
  • oaid

• Google Adsでプロモーションを行う場合は、下記のパラメータが必須となります。

  • platform
  • os_version
  • os_version_release
  • locale
  • device_model
  • build_id

特定のデバイスパラメータのみを取得するには、OptInParams()を使用します。下記具体例では、ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, and iadのみを取得しています。

BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

List<string> optInParams = new List<string> {"ip_address", "advertising_id", "developer_device_id", "limit_ad_tracking", "referrer", "iad"};
instance.OptInParams(optInParams);

instance.Connect();

特定のデバイスパラメータ以外のパラメータを取得するには、OptOutParams()メソッドを使用します。下記具体例では、locale, timezone, and build_id以外のパラメータを送信しています。

BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

List<string> optOutParams = new List<string> {"locale", "timezone", "build_id"};
instance.OptOutParams(optOutParams);

instance.Connect();

デバイスパラメータ

アプリ内課金イベント

iOSレシート検証

iOSのレシート検証には、transactionIdとreceiptが必要です。(signatureにはnullがセットされます) receiptにはUnityから受け取ったレシートのPayload(base64エンコードのASN.1レシート)を設定してください。

注：サブスクリプション課金の場合、 管理画面よりIAP shared secretを該当のアプリに追加してください。iOSのShared secretは、iTunes Connectのコンソールで > Select your app > Features > In-App Purchases > App-Specific Shared Secret　より取得できます。

Androidレシート検証

Androidのレシート検証には、receiptとsignatureが必要です。(transactionIdにはnullがセットされます)

重要: 管理画面のAppsタブ -> 該当のAndroidアプリ -> Editより、Public Keyを入力してください。Publick KeyはBase64でエンコードされたRSA公開キーで、Google Playデベロッパーコンソールのアプリ > 収益化の設定、の箇所から取得できます。 Androidの場合、現在サポート対象はGoogle Playからの課金トランザクションのみであることにご注意ください。

実装例

以下の例では、JSONデシリアライズに広く使用されているMiniJSONライブラリを使用しています。

  public static void OnProcessPurchase(PurchaseEventArgs purchaseEventArgs) {
    var price = purchaseEventArgs.purchasedProduct.metadata.localizedPrice;
    double lPrice = decimal.ToDouble(price);
    var currencyCode = purchaseEventArgs.purchasedProduct.metadata.isoCurrencyCode;

    var wrapper = Json.Deserialize(purchaseEventArgs.purchasedProduct.receipt) as Dictionary<string, object>;  // https://gist.github.com/darktable/1411710
    if (null == wrapper) {
        return;
    }

    var payload   = (string)wrapper["Payload"]; // For Apple this will be the base64 encoded ASN.1 receipt
    var productId = purchaseEventArgs.purchasedProduct.definition.id;

#if UNITY_ANDROID

  var gpDetails = Json.Deserialize(payload) as Dictionary<string, object>;
  var gpJson    = (string)gpDetails["json"];
  var gpSig     = (string)gpDetails["signature"];

  CompletedAndroidPurchase(productId, currencyCode, 1, lPrice, gpJson, gpSig);

#elif UNITY_IOS

  var transactionId = purchaseEventArgs.purchasedProduct.transactionID;

  CompletedIosPurchase(productId, currencyCode, 1, lPrice , transactionId, payload);

#endif

  }

  private static void CompletedAndroidPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string Receipt, string Signature)
  {
      BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
      instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, null, Receipt, Signature);
  }

  private static void CompletedIosPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string TransactionId, string Receipt)
  {
      BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
      instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, TransactionId, Receipt, null);
  }

免責事項: Tenjinで初めて課金イベントを実装する場合は、課金データを使用してユーザー獲得キャンペーンを拡大する前に、使用している他のツールでデータが正しいことを確認してください。

サブスクリプション

• 各サブスクリプション期間中に1度だけサブスクリプショントランザクションを送ってください。(例えば、月ごとのサブスクリプションの場合、1月に1度のトランザクション)

  

• iOSでサブスクリプション課金がある場合は、アプリのPublic KeyをTenjin管理画面上に追加して下さい。 アプリごとのShared SecretはiTunesコネクトのコンソール上で、アプリを選択 > Features > In-App Purchases > App-Specific Shared Secretから取得できます。

• iOSサブスクリプションの詳細については、こちらのドキュメントをご確認下さい。

• Androidサブスクリプションの詳細については、こちらのドキュメントをご確認下さい。

カスタムイベント

重要: カスタムイベント名は80文字以内に収めて下さい。また、ユニークなカスタムイベントの種類は500種類までにしてください。

• お使いのUnityプロジェクトにてAssetsフォルダを含めます。

• プロジェクト上で下記のメソッドを実装します。

  Tenjin.getInstance("<SDK_KEY>").SendEvent("name")
  

• イベント名、値を同時に送る場合には下記のメソッドを実装します。

  Tenjin.getInstance("<SDK_KEY>").SendEvent("nameWithValue","value")
  

• valueはinteger型としてください。valueがintejer出ない場合、イベントは送信されません。

下記がコードの例です。

void MethodWithCustomEvent(){
    //event with name
    BaseTenjin instance = Tenjin.getInstance ("SDK_KEY");
    instance.SendEvent("name");

    //event with name and integer value
    instance.SendEvent("nameWithValue", "value");
}

.SendEvent("name")は例えば、アプリ内のマイルストーンなどで実行されます。例えば、tutorial_complete、registration、level_1などです。

.SendEvent("name", "value")は特定のイベントに値を付随したい場合に使われます。例えば、("coins_purchased", "100") とするとコイン購入イベントでのコインの総数や平均を計算することができます。

サーバ間インテグレーション

Tenjinはサーバ間のインテグレーションもサポートしております(有償のプロダクト)。ドキュメントをご覧になりたい方は、support@tenjin.comまでメールをお送りいただき、料金についてご相談ください。

アプリサブバージョン

A/Bテストを実施する場合、appendAppSubversionメソッドを用いて、アプリバージョンに固定の数値を付加することが可能です。例えば、アプリのバージョンが1.0.1でappendAppSubversion: @8888をセットすると、レポートされるアプリバージョンは
1.0.1.8888となります。データボルトを用いれば、このアプリバージョンごとのパフォーマンスを分析することが可能です。

BaseTenjin instance = Tenjin.getInstance("<API KEY>");
instance.AppendAppSubversion(8888);
instance.Connect();

Live Opsキャンペーン

アプリ開発者は、自社サーバーまたはTenjinと連携していないネットワークにカスタムでコールバックを送信できます。これにより、開発者はこれらのユーザーレベルの属性データをリアルタイムで収集して分析できます。以下は、Tenjinのカスタムコールバックを使用した使用例です。

• 内製のデータ分析ツールがある場合、カスタム コールバックを使用すると、デバイス レベルごとに属性データをゲーム内データに関連付けることができます。

• ユーザーのアトリビューションソースに応じて、さまざまなアプリコンテンツを表示します。たとえば、ユーザーAがオーガニックに関連付けられ、ユーザーBが Facebookに関連付けられているとします。ユーザー Bの方がアプリに関心を持っている可能性が高いため、ユーザーがアプリをインストールした後に特別なゲーム内オファーを表示することができます。

より具体的な使用例について相談をご希望の場合は、Tenjinのサクセスマネージャーまでお問い合わせください。

カスタマーユーザID

イベントのパラメーターとして送信するカスタマーユーザIDを設定および取得できます。

.SetCustomerUserId("user_id")

.GetCustomerUserId()

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
instance.SetCustomerUserId("user_id");
string userId = instance.GetCustomerUserId(); 

イベントのキャッシュ/リトライ

リクエストが失敗した場合、またはユーザーがインターネットに接続していない場合のイベントとIAPの再試行とキャッシュを有効/無効にできます。これらのイベントは、新しいイベントがキューに追加され、ユーザーが接続を回復した後に送信されます。

.SetCacheEventSetting(true)

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
instance.SetCacheEventSetting(true);

インプレッションレベル広告収益の実装

Tenjinでは下記のメディエーションプロバイダにおいて、インプレッションレベルの広告収益(ILRD)をサポートしています。

• AppLovin
• Unity LevelPlay
• HyperBid
• AdMob
• Topon
• CAS

この機能を使用すると、ユーザーへの広告のインプレッションごとに広告収益に対応するイベントを受け取ることができます。この機能を有効にするには、以下の手順に従ってください。

テスト

実装が正しくできているかどうかを確認するには、SDK Live Dataを使用します。管理画面のDIAGNOSE-> Test devicesより、テストデバイスのリストにadvertising_idを追加します。SDK Live Dataにアクセスして、アプリからテストイベントを送信します。イベントがリアルタイムで確認できます。