旧バージョンのUnity SDK使用ガイド
Unity SDKはv2.0.0にアップグレードされました。このページは旧バージョンの使用ガイドです。新たに接続する場合は、最新のUnity SDK使用ガイドを参照してください
このガイドでは、Unity SDKを使ってプロジェクトに接続する方法を説明します。接続を始める前に、データルールの章をお読みになることをお勧めします。Unity SDKのソースコードはGitHubで入手できます。
最新バージョン: v1.4.4
更新日: 2020-04-17
1. SDKの初期化
1.1 SDKの統合
- Unity SDKのリソースファイルをダウンロードし、プロジェクトにインポートします:
Assets > Import Package > Custom Packageで、ダウンロードしたファイルを選択します
注意:AndroidプラグインはGradleで統合されるため、現在はUnity 5.4以降のバージョンにのみ対応しています。
- ThinkingAnalytics GameObjectを追加し、SDKの設定を行います
上図の各設定項目は次のとおりです:
Configuration
-
Enable Log:ログを有効にするかどうか。有効にすると送信状況が出力されるため、デバッグに便利です。Editorモードでもイベントが正しく送信されているかを確認でき、条件を満たさないプロパティは
warningログとしてコンソールに表示されます。 -
Network Type:サーバーにデータを送信するネットワーク条件を設定します。デフォルトは
DEFAULTです。選択できる値とその説明は次のとおりです:- DEFAULT:3G, 4G, 5GおよびWIFI環境でデータを送信します
- WIFI:WIFI環境でのみデータを送信します
- ALL:2G, 3G, 4G, 5GおよびWIFI環境でデータを送信します
-
Postpone Track:送信を遅延させるかどうかを設定します。このオプションを有効にすると、
StartTrack()を呼び出した後にデータの送信が始まり、呼び出すまでのデータはStartTrack()が呼び出されるまでキャッシュされます。ゲストIDまたは共通プロパティを設定する必要がある場合は、このオプションを有効にすることをお勧めします。呼び出し方法は遅延送信の部分を参照してください
Tokens
各Tokenが1つのインスタンスを表します。複数のプロジェクトにデータを送信する場合は、右下の「+」をクリックしてプロジェクトの設定を追加できます。複数プロジェクトでの注意事項は、この節の最後にある「複数プロジェクトのサポート」を参照してください。異なるAPP IDを持つ複数のToken設定を追加できます。
-
APP ID: 設定が必要です。プロジェクトのAPP_IDで、プロジェクトの申請時に発行されます。ここに入力してください。
-
SERVER URL: 設定が必要です。データ受信側のURLです:
- クラウドサービスをご利用の場合は、次のURLを入力してください:
- プライベートデプロイ版をご利用の場合は、次のURLを入力してください:
- https://データ収集アドレス
-
MODE: SDKインスタンスの実行モードです。本番環境では必ずNORMALモードを使用してください。詳しくはSDKモードを参照してください。
-
Auto Track:自動収集イベントを有効にするかどうか。チェックを入れると、SDKはゲームの起動と終了を自動的に記録します。詳しくは自動収集イベントを参照してください
-
TimeZone: v1.4.3以降で対応。データのデフォルトの基準タイムゾーンです。この設定は現在、イベント時間とユーザープロパティの設定時間にのみ適用され、プロパティ内のDateTime型には適用されません。
注意:一部のデバイスではデフォルトで平文での通信が禁止されているため、HTTPS形式の受信側URLを使用することを強く推奨します。
複数プロジェクトのサポート
SDKの設定時に複数のAPP IDを追加できます。その後APIを呼び出す際に、最後の引数でAPP IDを指定します。Identify()インターフェースを例にします:
// APP IDが“debug-appid”のAPP IDインスタンスにゲストIDを設定
ThinkingAnalyticsAPI.Identify("unity_debug_id", "debug-appid");
注意:ゲストID、アカウントID、共通プロパティなどは複数プロジェクト間で共有されないため、APP IDインスタンスごとに個別に設定する必要があります。
APP IDの引数を付けない場合は、デフォルトでリストの最初のAPP IDインスタンス(Token IDの後ろにdefaultと表示されているインスタンス)が使われます。リストの項目をドラッグして順序を変更することで、デフォルトのAPP IDインスタンスを変更できます。
1.2 SDKの使用
SDKの設定が完了したら、SDKを使ってイベントを送信できます。参考用のSampleも用意しています。
using ThinkingAnalytics;
ThinkingAnalyticsAPI.Track("unity_start");
2. ユーザーIDの設定
Unity SDKを使用すると、SDKはデフォルトでランダムなUUIDを各ユーザーのゲストIDとして使用します。このIDは、ユーザーが未ログインの状態での識別IDとして使われます。なお、デフォルトのゲストIDは、ユーザーがゲームを再インストールしたり、デバイスを変更したりすると変わります。
2.1 ゲストIDの設定(任意)
ゲームでユーザーごとに独自のゲストID管理体系がある場合は、Identifyを呼び出してゲストIDを設定できます:
ThinkingAnalyticsAPI.Identify("unity_id");
ゲストIDを取得するには、GetDistinctIdを呼び出します:
ThinkingAnalyticsAPI.GetDistinctId();
2.2 アカウントIDの設定とクリア
ユーザーがログインする際にLoginを呼び出してユーザーのアカウントIDを設定できます。アカウントIDを設定すると、アカウントIDがユーザーの識別IDとして使われます。設定したアカウントIDはLogoutを呼び出すまで保持されます:
// アカウントIDを設定
ThinkingAnalyticsAPI.Login("unity_user");
// アカウントIDをクリア
ThinkingAnalyticsAPI.Logout();
注意:このメソッドでは、ユーザーのログインやログアウトなどのイベントは送信されません。
3. イベントの送信
ThinkingAnalyticsAPI.Track()でイベントとそのプロパティを送信できます。通常、十数個から数百個の異なるイベントを送信することになります。AEを初めてお使いの場合は、まずいくつかの主要なイベントを送信することをお勧めします。
3.1 イベントの送信
事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することを推奨します。イベント名はstring型で、英字で始める必要があり、数字、英字、アンダースコア "_" を含めることができます。最大長は50文字で、英字の大文字と小文字は区別されません。
Dictionary<string, object> properties = new Dictionary<string, object>()
{
{"KEY_DateTime", DateTime.Now.AddDays(1)},
{"KEY_STRING", "B1"},
{"KEY_BOOL", true},
{"KEY_NUMBER", 50.65}
};
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties);
- イベントプロパティは
Dictionary<string, object>型で、各要素が1つのプロパティを表します。 - イベントプロパティの
Keyはプロパティ名で、string型です。英字で始める必要があり、数字、英字、アンダースコア "_" を含めることができます。最大長は50文字で、英字の大文字と小文字は区別されません。 - プロパティ値は、文字列、数値、
bool、DateTime、Listの5種類の型に対応しています。
注意:List型はv1.4.0以降のバージョンで対応しており、その要素はすべてstringに変換されて格納されます。
Track()を呼び出すと、SDKはシステムの現在時刻をイベントの発生時刻として使用します。イベント時間を指定する必要がある場合は、DateTime型の引数を渡してイベントのトリガー時間を設定できます。v1.3.0以降、SDKはDateTimeKindに基づいてイベント時間のオフセット(プリセットプロパティ#zone_offsetに対応)を送信できます。ただし、渡したDateTimeのKindプロパティがDateTimeKind.Unspecifiedの場合は、時間オフセットは送信されません:
DateTime dateTime = DateTime.Now.AddDays(-1);
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties, dateTime);
v1.4.3以降、SDKインスタンスのデフォルトのタイムゾーンを設定できます。Local以外のタイムゾーンを設定すると、すべてのイベント時間がそのタイムゾーンに揃えられ、渡したDateTimeのKindプロパティは無視されます。
注意:イベントの発生時間は設定できますが、受信側には次の制限があります:サーバー時間を基準に10日前から3日後までのデータのみを受信します。この範囲を超えたデータは異常データとみなされ、そのデータ全体が格納されません。
3.2 静的共通プロパティの設定
プレイヤーのサーバーやチャネルなどの重要なプロパティは、すべてのイベントに設定する必要があります。その場合は、これらのプロパティを共通イベントプロパティとして設定できます。共通イベントプロパティとは、すべてのイベントに付与されるプロパティのことです。SetSuperPropertiesを呼び出して共通イベントプロパティを設定できます。イベントを送信する前に、共通イベントプロパティを設定しておくことを推奨します。
Dictionary<string, object> superProperties = new Dictionary<string, object>()
{
{"SERVER", 0},
{"CHANNEL", "A3"}
};
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);
共通イベントプロパティはキャッシュに保存されるため、APPを起動するたびに呼び出す必要はありません。SetSuperPropertiesを呼び出して、以前に設定済みの共通イベントプロパティを送信した場合は、以前のプロパティが上書きされます。共通イベントプロパティとTrack()で送信したプロパティのKeyが重複する場合は、そのイベントのプロパティが共通イベントプロパティを上書きします。
共通イベントプロパティを削除する場合は、UnsetSuperProperty()を呼び出して特定の共通イベントプロパティをクリアできます。すべての共通イベントプロパティをクリアする場合は、ClearSuperProperties()を呼び出します。
// プロパティ名がCHANNELの共通プロパティをクリア
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");
// すべての共通プロパティをクリア
ThinkingAnalyticsAPI.ClearSuperProperties();
3.3 動的共通プロパティの設定
共通プロパティの値が定数でない場合は、動的共通プロパティを設定することで実現できます。動的共通プロパティもすべてのイベントに追加され、イベントの送信時に実際の値が動的に取得されます。
動的共通プロパティを設定するには、まず動的共通プロパティのクラスを作成してIDynamicSuperPropertiesインターフェースを実装し、public Dictionary<string, object> GetDynamicSuperProperties()メソッドをオーバーライドします。このメソッドの戻り値が、設定する動的共通プロパティになります。次にSetDynamicSuperPropertiesを呼び出して動的共通プロパティのオブジェクトを渡します。例は次のとおりです:
using ThinkingAnalytics;
// 動的共通プロパティの実装を定義します。この例ではUTC時間の動的共通プロパティを設定します
public class DynamicProp : IDynamicSuperProperties
{
public Dictionary<string, object> GetDynamicSuperProperties()
{
return new Dictionary<string, object>() {
{"KEY_UTCTime", DateTime.UtcNow}
};
}
}
ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());
注意:イベントプロパティ名が重複する場合、動的共通プロパティの優先度は共通イベントプロパティより高く、Trackで設定したイベントプロパティより低くなります。
3.4 イベントの所要時間の記録
イベントの所要時間を記録する必要がある場合は、TimeEvent()を呼び出して計測を開始し、計測するイベント名を指定します。そのイベントを送信すると、記録された所要時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。
// TimeEventを呼び出してTIME_EVENTイベントの計測を開始
ThinkingAnalyticsAPI.TimeEvent("TIME_EVENT");
// do some thing...
// TrackでTIME_EVENTイベントを送信すると、プロパティに#durationプロパティが追加されます
ThinkingAnalyticsAPI.Track("TIME_EVENT");
4. ユーザープロパティ
AEプラットフォームが現在対応しているユーザープロパティの設定インターフェースは、UserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppendです。
4.1 UserSet
一般的なユーザープロパティは、UserSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は、新しく作成されます。
ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>()
{
{"USER_PROP_NUM", 0},
{"USER_PROP_STRING", "A3"}
});
イベントプロパティと同様です:
- ユーザープロパティは
Dictionary<string, object>型で、各要素が1つのプロパティを表します。 - ユーザープロパティの
Keyはプロパティ名で、string型です。英字で始まり、数字、英字、アンダースコア“_”のみを含めることができます。最大長は50文字で、英字の大文字と小文字は区別されません。 - ユーザープロパティの値は、文字列、数値、
bool、DateTime、Listの5種類の型に対応しています。
注意:List型はv1.4.0以降のバージョンで対応しており、その要素はすべてstringに変換されて格納されます。
4.2 UserSetOnce
送信するユーザープロパティを一度だけ設定すればよい場合は、UserSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます:
ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>()
{
{"USER_PROP_NUM", -50},
{"USER_PROP_STRING", "A3"}
});
注意:UserSetOnceで設定するユーザープロパティの型と制限条件はUserSetと同じです。
4.3 UserAdd
数値型のプロパティを送信する場合は、UserAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。
ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>()
{
{"USER_PROP_NUM", -100.9},
{"USER_PROP_NUM2", 10.0}
});
注意:UserAddのプロパティの型とKeyの制限はUserSetと同じですが、Valueには数値型のプロパティのみ送信できます。
4.4 UserUnset
ユーザーの特定のプロパティをリセットする場合は、UserUnsetを呼び出して、そのユーザーの指定したユーザープロパティの値をクリアできます。このインターフェースには、文字列またはリスト型のパラメータを渡せます:
// 単一のユーザープロパティを削除
ThinkingAnalyticsAPI.UserUnset("userPropertyName");
// 複数のユーザープロパティを削除
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");
ThinkingAnalyticsAPI.UserUnset(listProps);
4.5 UserDelete
あるユーザーを削除する場合は、UserDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。
ThinkingAnalyticsAPI.UserDelete();
4.6 UserAppend
v1.4.0以降、UserAppendを呼び出して、List型のユーザープロパティに要素を追加できます:
List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
stringList.Add("cat");
// プロパティ名がUSER_LISTのユーザープロパティに3つの要素を追加
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>
{
{"USER_LIST", stringList }
});
5. 自動収集イベント
SDKの設定時にAuto Trackオプションにチェックを入れると、SDKは次のイベントを自動的に記録します:
ta_app_start:ゲーム起動イベント。ユーザーがフォーカスを得るたびに(つまりゲーム中に)トリガーされますta_app_end:ゲーム終了イベント。ゲームがPause状態になるとトリガーされ、#durationプロパティが付与されて今回のプレイ時間(単位は秒)が記録されます
バージョン1.1.0以降は、インターフェースを呼び出してインストールイベントを収集できます:
// APPインストールイベントを収集
ThinkingAnalyticsAPI.TrackAppInstall();
ta_app_install:ゲームインストールイベント。インストールイベントは、ユーザーがインストール後に初めてAPPを開いたときにのみトリガーされます。APPをアップグレードしてもトリガーされませんが、APPを削除して再インストールすると再度トリガーされます。
6. その他の設定オプション
6.1 デバイスIDの取得
SDKは初期化が完了すると自動的にデバイスIDを生成し、ローカルキャッシュに記録します。同じアプリ/ゲームでは、1台のデバイスのデバイスIDは変わりません。GetDeviceId()を呼び出してデバイスIDを取得できます:
ThinkingAnalyticsAPI.GetDeviceId();
// デバイスIDをゲストIDとして使用
// ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());
6.2 遅延送信
Postpone Trackオプションにチェックを入れた場合、すべての送信リクエスト(ユーザープロパティの設定とイベントのトラッキングを含む)は、次のメソッドを明示的に呼び出すまでキャッシュされます:
ThinkingAnalyticsAPI.StartTrack();
このインターフェースが呼び出されてから、データの送信が始まります。このインターフェースの呼び出し前に生成されたデータには、送信時に改めて設定したユーザーIDと共通プロパティが付与されます。そのため、StartTrack()を呼び出す前にユーザーIDと共通プロパティを設定すれば、すべてのデータに適用されます。ゲストIDや共通プロパティを設定する必要があるケースに適しています:
//ゲストIDを設定
ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());
//共通プロパティを設定
Dictionary<string, object> superProperties = new Dictionary<string, object>()
{
{"SERVER", 0},
{"CHANNEL", "A3"}
};
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);
//送信開始インターフェースを呼び出し
ThinkingAnalyticsAPI.StartTrack();
6.3 データ送信の一時停止/停止
v1.2.0で、SDKのデータ送信を停止する機能が追加されました。SDKの送信を停止するインターフェースは2種類あります:
- SDKの送信の一時停止(EnableTracking)
テスト環境にいるユーザーや、テストアカウントでログインしたユーザーなど、一部のケースではSDKのデータ収集と送信を一時的に停止したい場合があります。その場合は、次のインターフェースを呼び出してSDKの送信を一時停止できます。
任意のインスタンス(メインインスタンスとライトインスタンスを含む)でEnableTrackingを呼び出し、falseを渡すとSDKの送信を一時停止できます。そのインスタンスで設定済みの#distinct_id、#account_id、共通プロパティなどは保持されます。そのインスタンスで収集済みで、まだ送信に成功していないデータは引き続き送信が試行されます。以降、そのインスタンスでは新しいデータの収集と送信、ゲストID、アカウントID、共通プロパティなどの設定はできなくなりますが、そのインスタンスで設定済みの共通プロパティ、デバイスID、ゲストID、アカウントIDなどの情報は読み取ることができます。
インスタンスの停止状態はローカルキャッシュに保存されます。EnableTrackingを呼び出してtrueを渡すと、SDKインスタンスはデータの収集と送信を再開します。なお、ライトインスタンスはキャッシュされないため、APPを開くたびにライトインスタンスの一時停止状態は保持されず、送信が再開されます。
// デフォルトインスタンスの送信を一時停止します。キャッシュ済みのデータと設定済みの情報はクリアされません
ThinkingAnalyticsAPI.EnableTracking(false);
// デフォルトインスタンスの送信を再開
ThinkingAnalyticsAPI.EnableTracking(true);
- SDKの送信の停止(OptOutTracking)
特殊なケースでは、SDKの機能を完全に停止する必要がある場合があります。たとえば、GDPRが適用される地域でユーザーがデータ収集の許可を拒否した場合は、次のインターフェースを呼び出してSDKの機能を完全にオフにできます。
OptOutTrackingはメインインスタンスからのみ呼び出せます。EnableTrackingとの最大の違いは、そのインスタンスのローカルキャッシュ(このインスタンスのゲストID、アカウントID、共通プロパティ、未送信のデータキューを含む)をクリアしたうえで、そのインスタンスの収集・送信機能をオフにする点です。
// デフォルトインスタンスの送信を停止し、ローカルキャッシュをクリア
ThinkingAnalyticsAPI.OptOutTracking();
SDKの機能をオフにすると同時に、AEクラスター内のそのユーザーのユーザーデータを削除したい場合は、OptOutTrackingAndDeleteUserを呼び出します。SDKインスタンスの機能を停止する前にUserDeleteデータが1件送信され、そのユーザーのユーザーデータが削除されます。
// デフォルトインスタンスの送信を停止し、user_delを送信
ThinkingAnalyticsAPI.OptOutTrackingAndDeleteUser();
インスタンスの停止状態もローカルキャッシュに保存されます。OptInTrackingを呼び出すと以降は送信を再開できますが、その時点で新しいインスタンスと同じ状態になります
// 送信を再開
ThinkingAnalyticsAPI.OptInTracking();
6.4 ライトインスタンスの作成
ライトインスタンスを使用すると、同じAPP IDで複数のインスタンスを作成できます
// ライトインスタンスを作成し、ライトインスタンスのtoken(APP IDに相当)を返す
string lightToken = ThinkingAnalyticsAPI.CreateLightInstance();
// ライトインスタンスにアカウントIDを設定
ThinkingAnalyticsAPI.Login("anotherAccount", lightToken);
// ライトインスタンスでイベントを送信
ThinkingAnalyticsAPI.Track("TEST_EVENT", lightToken);
注意:子ライトインスタンスは、親インスタンスとAPP ID、送信先URL、一部の設定が同じですが、その他の情報は共有されません
6.5 SDKの実行モード
v1.4.0以降、SDKは3つのモードでの実行に対応しています:
- NORMAL: 通常モード。データはキャッシュに保存され、一定のキャッシュ戦略に従って送信されます
- DEBUG: Debugモード。データを1件ずつ送信します。問題が発生した場合は、ログと例外でユーザーに通知します
- DEBUG_ONLY: Debug Onlyモード。データの検証のみを行い、データは格納されません
注意: DEBUGモードは統合段階でのデータ検証にのみ使用し、本番環境では使用しないでください。
デバッグモードが本番環境で有効になるのを防ぐため、指定したデバイスでのみデバッグモードを有効にできます。クライアントでデバッグモードを有効にし、かつAE管理画面の「データ」→「データ収集管理」→「デバッグモード」ページにデバイスIDが追加されているデバイスのみ、デバッグモードを有効にできます。追加方法:このページで右上の「デバイスに接続」をクリックし、「デバイスの選択」ドロワーで「デバイスを追加」をクリックして、デバイスIDを入力します。
デバイスIDは、次の3つの方法で取得できます:
- AEプラットフォームのイベントデータに含まれる#device_idプロパティ
- クライアントログ:SDKの初期化が完了すると、デバイスのDeviceIdが出力されます
- インスタンスのインターフェースを呼び出す:デバイスIDの取得
Release Note
v1.4.4 2020/04/17
- カスタムCultureInfoを使用する場合にDouble型の形式が正しくならない問題を修正
v1.4.3 2020/03/19
- データの#timeプロパティのデフォルトタイムゾーンの設定に対応
- ネイティブSDKのバージョンを更新
v1.4.2 2020/02/21
- iOSプラグインを更新し、古いバージョンのiOSで発生していたバグを修正
v1.4.1 2020/02/14
- Unity 2019.3.1f1に対応
v1.4.0 2020/02/11
- プロパティ値がList / Array型に対応
- UserAppendインターフェースを追加
- Debugモードでのデータ検証に対応
- インスタンスごとに受信側URLを個別に設定できるように対応
- ローカルでのデータ形式の検証を削除
v1.3.1 2019/12/25
- Android 4.3未満のバージョンで終了時にタイムアウトする問題を修正
- iOS開発環境が含まれていない場合のエラーを修正
v1.2.0 2019/09/02
- データ送信のオフ/オンに対応
- データ送信の一時停止/再開に対応
- ライトインスタンスに対応
- 2019.2.1fでネットワークタイプの設定に失敗する問題を修正
- timeEventが不正確になる問題を修正
- Android/iOS SDKを2.1.0にアップグレード
v1.1.0 2019/08/09
- デバイスIDの取得に対応
- 動的共通プロパティに対応
- インストールイベントの収集に対応
- 組み込みのAndroid SDKを2.0.2にアップグレード
- 組み込みのiOS SDKを2.0.1にアップグレード
- 送信のキャッシュオプションに対応。
StartTrack()を明示的に呼び出して送信を開始するかどうかを選択できます
v1.0.0 2019/06/20
- ゲストIDとユーザーアカウントの設定に対応
- イベントとユーザープロパティの送信に対応
ta_app_startとta_app_endイベントの自動送信に対応- 共通プロパティのインターフェースに対応
timeEventインターフェースに対応- 複数プロジェクトへの送信に対応

