Unity SDK実装手順

Tenjin Unity SDKでは、iOS及びAndroidの両方をサポートしています。
過去のバージョン履歴については、こちらのリリースノートを御覧ください。
iOSおよびAndroidのドキュメントをご確認いただき、ビルドに適切なプラットフォーム設定を適用ください。
ご質問がある方は、support@tenjin.comまでお問い合わせください。
iOSについての注意事項:
1. v1.12.0以上のバージョンのiOS SDKを使用する場合は、Xcode 12の使用が必要となります。
2. iOSのビルドに際し、下記のフレームワークがXcodeのビルドに自動的に追加されていることをご確認ください。もしされていない場合は、不足しているフレームワークをマニュアルで追加してください。
  - AdServices.framework
  - AdSupport.framework
  - AppTrackingTransparency.framework
  - iAd.framework
  - StoreKit.framework
3. AppTrackingTransparencyを使用する場合、.plistファイルのアップデート、Privacy - Tracking Usage Description (NSUserTrackingUsageDescription)の追加及びユーザに表示するテキストメッセージの追加を行ってください。
4. Appleサーチアドアトリビューションをお使いの場合、SDKのバージョンをv1.12.6以上にし、AdServices.frameworkライブラリを追加してください。

Androidについての注意事項:

すでにGoogle Play ServiceがインストールされているSDK、またはPlayServiceResolverをお使いの場合、下記のファイルを削除する必要があります。 /Assets/Plugins/Android/play-services-ads-identifier--*.aar,/Assets/Plugins/Android/play-services-basement---*.aar

Unityバージョン2019以降で他のSDKとTenjin SDKを併用していて、AndroidのビルドにGradleを使用している場合、DuplicateMethodExceptionなどのビルドエラーが発生したり、リファラインストールが機能しないケースがあります。その場合は、下記手順をお試し下さい。

Assets/Plugins/Androidフォルダよりtenjin.aar以外の全ての*.aarファイルを削除。

mainTemplate.gradleファイルに下記を追加。

     // Android Resolver Repos Start
     ([rootProject] + (rootProject.subprojects as List)).each { project ->
         project.repositories {
             def unityProjectPath = $/file:///**DIR_UNITYPROJECT**/$.replace("\\", "/")
             maven {
                 url "https://maven.google.com"
             }
             maven {
                 url "https://s3.amazonaws.com/moat-sdk-builds"
             }
             maven {
                 url 'https://developer.huawei.com/repo/'
             }
             mavenLocal()
             jcenter()
             mavenCentral()
             google()
         }
     }

 // Android Resolver Repos End
     apply plugin: 'com.android.library'
     **APPLY_PLUGINS**
     dependencies {
         implementation fileTree(dir: 'libs', include: ['*.jar'])
     // Android Resolver Dependencies Start
        implementation 'com.android.support:multidex:1.0.1'
        implementation 'com.google.android.gms:play-services-analytics:{version}'
        implementation 'com.android.installreferrer:installreferrer:{version}'
        implementation 'com.huawei.hms:ads-identifier:{version}'
        implementation 'com.huawei.hms:ads-installreferrer:{version}'
        androidTestImplementation('com.android.support.test.espresso:espresso-core:2.2.2', {
            exclude group: 'com.android.support', module: 'support-annotations'
        })
     // Android Resolver Dependencies End
     **DEPS**}

gradleTemplate.propertiesファイルに下記の行を追加。
```
android.useAndroidX=true
```

アプリ起動時に下記のエラーが発生した場合、tenjin.aarのファイルを/Assets/Plugins/Android/Tenjin/libsから/Assets/Plugins/Androidに移動してください。

   AndroidJavaException: java.lang.NoSuchMethodError: no static method with name='setWrapperVersion'

または

   AndroidJavaException: java.lang.ClassNotFoundException: com.tenjin.android.TenjinSDK

SDK実装手順

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

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

OAIDとOtherアンドロイドアプリストア

TenjinはAndroidのOAIDを使用したAndroidアプリストアのトラッキングをサポートしています。OAIDライブラリを実装した場合のオプションは下記の通りです。Google Play以外のアプリを開発する場合は、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に設定します。

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.setAppStore(TenjinSDK.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に設定します。

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.other);

SDK初期化

管理画面よりAPI_KEYを取得します。
プロジェクト内の初回の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("<API_KEY>");

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

アプリストア設定

デフォルトではGoogle Playがアプリストアになっています。 Google Play以外のアプリの場合は、TenjinSDK.AppStoreType.*の値を適切に設定してください。

AndroidManifest.xml:

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

setAppStore():

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.{{APP_STORE_TYPE_VALUE}});

AppStoreTypeのオプションは下記の通りです。

googleplay
amazon
other

ATTrackingManager

iOS 14では、ATTrackingManagerを使用して許可プロンプトを表示し、ユーザをオプトイン/オプトアウトする事が可能です。デバイスがトラッキングの許可を行わない場合は、IDFAはゼロとなります。デバイスがトラッキングの許可を行った場合、connect()メソッドを通じてIDFAがサーバ側に送られます。 ATTrackingManagerを使用せずに、Tenjinのconnect()処理を行うことも可能です。ATTrackingManagerの許可プロンプトの実装は2021年初春のiOS14.5のリリースまでの間は必須ではありません。

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("API_KEY");

#if UNITY_IOS

      // Tenjin wrapper for requestTrackingAuthorization
      instance.RequestTrackingAuthorizationWithCompletionHandler((status) => {
        Debug.Log("===> App Tracking Transparency Authorization Status: " + status);

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

      });

#elif UNITY_ANDROID

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

#endif
    }
}

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

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

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

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("API_KEY");

#if UNITY_IOS

      // Registers SKAdNetwork app for attribution
      instance.RegisterAppForAdNetworkAttribution();

      // 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.UpdateConversionValue(<YOUR 6 bit value>);

#elif UNITY_ANDROID

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

#endif
    }
}

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

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

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

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

注:メディエーションにAppLovin MAXを使用している場合、NSAdvertisingAttributionReportEndpointに入力された値がビルドプロセス中にAppLovinのURLで上書きされてしまいます。その場合、XCode上で下記の手順によりNSAdvertisingAttributionReportEndpointをhttps://tenjin-skan.comに上書きすることが可能です。

こちらの手順で、iOSアプリをエクスポートします。
iOSアプリをビルドした後、こちらのストラクチャーを持つXCodeのプロジェクトが生成されます。https://docs.unity3d.com/Manual/StructureOfXcodeProject.html
XCodeプロジェクト上のInfo.plistにナビゲートし、マニュアルでNSAdvertisingAttributionReportEndpointをhttps://tenjin-skan.comに変更します。

または、AppLovinのアカウントマネージャに依頼し、ポストバックの転送設定を行うことも可能です。

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

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

void Start () {

  BaseTenjin instance = Tenjin.getInstance("API_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を使用したネットワークでプロモーションを実施する場合は、下記のパラメータが必須となります。
- oaid
- imei
Google Adsでプロモーションを行う場合は、下記のパラメータが必須となります。
- platform
- os_version
- locale
- device_model
- build_id

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

void Start () {

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

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

  instance.Connect();
}

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

void Start () {

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

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

  instance.Connect();
}

デバイスパラメータ

パラメータ	詳細	プラットフォーム	参照
ip_address	IPアドレス	All
advertising_id	広告ID	All	リンク)
developer_device_id	ベンダーID	iOS
oaid	Open Advertising ID	Android	リンク
imei	Device IMEI	Android	リンク
limit_ad_tracking	limit ad tracking enabled	All	リンク
platform	platform	All
referrer	Google Play Install Referrer	Android	リンク
iad	Apple Search Adパラメータ	iOS	リンク
os_version	OSバージョン	All	リンク
device	デバイス名	All	リンク
device_manufacturer	デバイス製造元	Android	リンク
device_model	デバイスモデル	All	リンク
device_brand	デバイスブランド	Android	リンク
device_product	デバイスプロダクト	Android	リンク
device_model_name	デバイスマシン	iOS	iOS (hw.model)
device_cpu	デバイスCPU	iOS	iOS (hw.cputype)
carrier	キャリア	Android	リンク
connection_type	セルラーまたはWifi	Android	リンク
screen_width	デバイススクリーン幅	Android	リンク
screen_height	デバイススクリーン高さ	Android	リンク
os_version_release	リリース時OSバージョン	All	リンク
build_id	ビルドID	All	リンク
locale	デバイスロケール	All	リンク
country	ロケール国	All	Android>), iOS
timezone	タイムゾーン	All	Android, iOS

アプリ内課金イベント

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を入力してください。 Public Keyはお客様のGoogle Play dashboardの"Services & APIs"から取得できます。

実装例：

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("API_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("API_KEY");
         instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, TransactionId, Receipt, null);
     }
 }

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

サブスクリプション

各サブスクリプション期間中に1度だけサブスクリプショントランザクションを送ってください。(例えば、月ごとのサブスクリプションの場合、1月に1度のトランザクション)
Tenjinは重複したトランザクションの重複排除は行いません。
iOSでサブスクリプション課金がある場合は、アプリのPublic KeyをTenjin管理画面上に追加して下さい。アプリごとのShared SecretはiTunesコネクトのコンソール上で、アプリを選択 > Features > In-App Purchases > App-Specific Shared Secretから取得できます。
iOSサブスクリプションの詳細については、こちらのドキュメントをご確認下さい。
Androidサブスクリプションの詳細については、こちらのドキュメントをご確認下さい。

カスタムイベント

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

お使いのUnityプロジェクトにてAssetsフォルダを含めます。
プロジェクト上で下記のメソッドを実装します。

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

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

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

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

下記がコードの例です。

void MethodWithCustomEvent(){
    //event with name
    BaseTenjin instance = Tenjin.getInstance ("API_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のトラッキングURL経由でユーザがインストールした後、そのユーザをアプリ内の特定ページに遷移させることが可能です。getDeeplinkメソッドとコールバックにより、ディファードディープリンクにアクセスすることが可能です。詳細なテスト手順はこちらをご確認ください。


public class TenjinExampleScript : MonoBehaviour {

  // Use this for initialization
  void Start () {
    BaseTenjin instance = Tenjin.getInstance("API_KEY");
    instance.Connect();
    instance.GetDeeplink(DeferredDeeplinkCallback);
  }

  public void DeferredDeeplinkCallback(Dictionary<string, string> data) {
    bool clicked_tenjin_link = false;
    bool is_first_session = false;

    if (data.ContainsKey("clicked_tenjin_link")) {
      //clicked_tenjin_link is a BOOL to handle if a user clicked on a tenjin link
      clicked_tenjin_link = (data["clicked_tenjin_link"].ToLower() == "true");
      Debug.Log("===> DeferredDeeplinkCallback ---> clicked_tenjin_link: " + clicked_tenjin_link);
    }

    if (data.ContainsKey("is_first_session")) {
      //is_first_session is a BOOL to handle if this session for this user is the first session
      is_first_session = (data["is_first_session"].ToLower() == "true");
      Debug.Log("===> DeferredDeeplinkCallback ---> is_first_session: " + is_first_session);
    }

    if (data.ContainsKey("ad_network")) {
      //ad_network is a STRING that returns the name of the ad network
      Debug.Log("===> DeferredDeeplinkCallback ---> adNetwork: " + data["ad_network"]);
    }

    if (data.ContainsKey("campaign_id")) {
      //campaign_id is a STRING that returns the tenjin campaign id
      Debug.Log("===> DeferredDeeplinkCallback ---> campaignId: " + data["campaign_id"]);
    }

    if (data.ContainsKey("advertising_id")) {
      //advertising_id is a STRING that returns the advertising_id of the user
      Debug.Log("===> DeferredDeeplinkCallback ---> advertisingId: " + data["advertising_id"]);
    }

    if (data.ContainsKey("deferred_deeplink_url")) {
      //deferred_deeplink_url is a STRING that returns the deferred_deeplink of the campaign
      Debug.Log("===> DeferredDeeplinkCallback ---> deferredDeeplink: " + data["deferred_deeplink_url"]);
    }

    if (clicked_tenjin_link && is_first_session) {
      //use the deferred_deeplink_url to direct the user to a specific part of your app
      if (String.IsNullOrEmpty(data["deferred_deeplink_url"]) == false) {
      }
    }
  }
}

下記がディファードディープリンクコールバック内で取得できるパラメータの一覧です。

パラメータ	説明
advertising_id	デバイスの`Advertising ID`
ad_network	キャンペーンのネットワーク名
campaign_id	TenjinキャンペーンID
campaign_name	Tenjinキャンペーン名
site_id	パブリッシャーID
referrer	インストーリリファラ
deferred_deeplink_url	キャンペーンのディファードディープリンクURL
clickedTenjinLink	Tenjinによってデバイスがトラックされたかどうかの真偽値
isFirstSession	各デバイスごとの初回起動かどうかの真偽値

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

Tenjinはサーバ間のインテグレーションもサポートしております。ドキュメントをご覧になりたい方は、support@tenjin.comまでメールをお送りください。

アプリサブバージョン:

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

[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK appendAppSubversion:@8888];
[TenjinSDK connect];

Unityプラグイン