Unity SDK実装手順
- Tenjin Unity SDKでは、iOS及びAndroidの両方をサポートしています。
- 過去のバージョン履歴については、こちらのリリースノートを御覧ください。
- iOSおよびAndroidのドキュメントをご確認いただき、ビルドに適切なプラットフォーム設定を適用ください。
- ご質問がある方は、support@tenjin.comまでお問い合わせください。
iOSについての注意事項:
- v1.12.0以上のバージョンのiOS SDKを使用する場合は、Xcode 12の使用が必要となります。
- iOSのビルドに際し、下記のフレームワークがXcodeのビルドに自動的に追加されていることをご確認ください。もしされていない場合は、不足しているフレームワークをマニュアルで追加してください。
- AdServices.framework
- AdSupport.framework
- AppTrackingTransparency.framework
- iAd.framework
- StoreKit.framework
- AppTrackingTransparencyを使用する場合、
.plist
ファイルのアップデート、Privacy - Tracking Usage Description
(NSUserTrackingUsageDescription)の追加及びユーザに表示するテキストメッセージの追加を行ってください。 - 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バージョン2020.1.16f1以降で他の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() 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.3' 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:3.0.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
- すでにGoogle Play ServiceがインストールされているSDK、またはPlayServiceResolverをお使いの場合、下記のファイルを削除する必要があります。
目次
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
デモプロジェクトtenjin-unity-sdk-demoは、tenjin-unity-sdkの実装サンプルです。
Google Play
デフォルトでは、unspecifiedがデフォルトのAppStoreです。アプリをGooglePlayストアで配布する場合は、アプリストアの値をgoogleplayに更新します。
App StoreTypeの値を googleplay
に設定します。
BaseTenjin instance = Tenjin.getInstance("<API_KEY>");
instance.SetAppStoreType(AppStoreType.googleplay);
Amazonストア
By default, unspecified is the default App Store. Update the app store value to amazon, if you distribute your app on Amazon store.
Set your App Store Type value to amazon
:
BaseTenjin instance = Tenjin.getInstance("<API_KEY>");
instance.SetAppStoreType(AppStoreType.amazon);
Otherアンドロイドアプリストア
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
に設定します。
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();
}
}
アプリストア設定
下記の3つのアプリストアのオプションをサポートしています。
- googleplay
- amazon
- other
デフォルトでは, unspecifiedがアプリストアの設定になります。特定のアプリストアにパブリッシュする場合は、アプリストアを適切な値に設定してください。otherのアプリストアはHuaweiアプリギャラリーやその他のアプリストアで使用されます。
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}});
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
}
}
ATT許可プロンプトの表示
AppleのATTガイドラインに準拠するには、ATT許可プロンプトの説明を入力し、アプリケーションへの許可リクエストを実装する必要があります。
注: ゲーム内で広告を配信する前に、許可リクエストを実装する必要があります。
ユーザー追跡の説明の設定
XcodeプロジェクトのInfo.plist
ファイル内のNSUserTrackingUsageDescription
キーを使用して説明の内容を設定します。デバイス追跡データの使用許可を要求している理由をユーザーに通知するメッセージを提供する必要があります。
- Xcodeプロジェクトナビゲータで、
Info.plist
ファイルを開きます。 - プロパティリストエディタの任意のキーの横にある追加ボタン(+)をクリックして、新しいプロパティキーを作成します。
- キー名
NSUserTrackingUsageDescription
を入力します。 - 文字列値のタイプを選択します。
- 値フィールドにアプリ追跡のメッセージを入力します。いくつかの例が含まれます:
- お客様のデータを使用して、より優れたパーソナライズされた広告エクスペリエンスを提供します。
- 使用しているアプリ、使用しているデバイス、使用している国に基づいて、最も興味のあるアプリや製品の広告を表示するようにしています。
- 私たちは、あなたが使用するアプリに基づいて、あなたにとって最も興味深いアプリや製品の広告を表示しようとします。
注: Appleは、プライバシー関連の機能に直面しているすべてのエンドユーザーの許容可能な使用とメッセージングを定義する特定の[アプリストアガイドライン](https://developer.apple.com/app-store/user-privacy-and-data-use/)を提供しています。Tenjinは法律上の助言を提供していません。したがって、このページの情報は、お客様のビジネスとプロセスの法的要件、およびそれらに対処する方法を決定するための法的手段の代替ではありません。
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
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
- Android
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
メソッドとコールバックにより、ディファードディープリンクにアクセスすることが可能です。
ディファードディープリンクの機能は有償の機能となります。料金の詳細については、お客様のアカウントマネージャにお問い合わせください。
サーバ間インテグレーション:
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];
インプレッションレベル広告収益の実装
Tenjinでは下記のメディエーションプロバイダにおいて、インプレッションレベルの広告収益(ILRD)をサポートしています。
- AppLovin
- IronSource
- HyperBid
- AdMob
- Topon
この機能を使用すると、ユーザーへの広告のインプレッションごとに広告収益に対応するイベントを受け取ることができます。この機能を有効にするには、以下の手順に従ってください。
ILRDは有償のプロダクトとなります。料金については、お客様のアカウントマネージャまでお問い合わせください。
テスト
実装が正しくできているかどうかを確認するには、SDK Live Dataを使用します。
管理画面のDIAGNOSE-> Test devicesより、テストデバイスのリストにadvertising_id
を追加します。
SDK Live Dataにアクセスして、アプリからテストイベントを送信します。イベントがリアルタイムで確認できます。