Unity - Advanced

アカウントID設定

SDKインスタンスはランダムのUUIDでユーザーのゲストIDとして付与します。ゲストIDはユーザーがログインする前のユーザー識別IDとして使われます。ただし、事前に注意すべきのは、アカウントIDはユーザー再インストールすると変更されます。

1.1 ゲストID設定

::: Tips

一般的には、ゲストIDを手動設定することは不要で、ユーザー識別ルールを確認した上で、ゲストID設定を行なってください。

もしゲストIDを変更したい場合は、SDKを初期設定したあとですぐ呼び出すように設定してください。

:::

独自でゲストIDの管理体制がある場合は、identifyを呼び出して、ゲストIDを設定してください

// set distinct ID as Thinker
ThinkingAnalyticsAPI.Identify("Thinker");

現在のゲストIDを取得したい場合は、GetDistinctIdを呼び出して取得できます。

// return distinct ID
String distinctId = ThinkingAnalyticsAPI.GetDistinctId();

1.2 アカウントID設定

ユーザーログイン時に、Loginを呼び出してアカウントIDを設定できます。TEはアカウントIDをユーザー身分の識別IDとして使われています。一度設定されたアカウントIDはLogoutを呼び出す前に保存されます。Loginを多数呼び出した場合は、その前のアカウントIDを上書きされます。

// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
ThinkingAnalyticsAPI.Login("TA");

この方法ではログインイベントとして送信されません

1.3 アカウントIDをクリア

ユーザーがログアウトイベントを行う前に、Logoutを呼び出して、アカウントIDをクリアすることができます。もう一度Loginを呼び出す前にゲストIDはユーザー身分の識別IDとして使われます。

ThinkingAnalyticsAPI.Logout();

ユーザーがアカウントを削除する際にLogoutを呼び出すよう設定してください。

ログアウトイベントとして送信されません。

イベント送信

SDKが初期化設定完了後、データプランに応じて、トラッキングコードを実装し、ユーザーの行動データを収集することができます。一般的には、通常イベント送信は十分収集可能で、実際業務シーンによって、初回・更新可能などの特殊イベント収集することも可能です。

2.1 通常イベント

track を呼び出して、データプランに応じてイベントのプロパティを設定の上、データ送信できます。

例：アイテム購入

Dictionary<string, object> properties = new Dictionary<string, object>(){
    {"product_name", "product name"}
};
ThinkingAnalyticsAPI.Track("product_buy", properties);

2.2 初回イベント

初回イベントはあるデバイスもしくはその他分析主体のIDごとで、1回目のみ記録されるイベントとなります。

例えば：あるデバイスのアクティブイベントはそれを使って便利です

Dictionary<string, object> properties = new Dictionary<string, object>(){
    {"key", "value"}
};
ThinkingAnalyticsAPI.Track(new TDFirstEvent("device_activation", properties));

もしデバイス以外で初回判断したい場合は、first_check_idで初回イベントを定義してください。

//set the user ID as the first_check_id of the first event to track the first initialization event of the user.
Dictionary<string, object> properties = new Dictionary<string, object>(){
    {"key", "value"}
};
TDFirstEvent firstEvent = new TDFirstEvent("account_activation", properties);
firstEvent.SetFirstCheckId("TE");
ThinkingAnalyticsAPI.Track(firstEvent);

注意：サーバ側で初回なのかを検証するため、初回イベントはデフォルトで1時間遅延して格納されます。

2.3 更新可能イベント

通常イベントはデータを格納されたら更新不可となりますが、データ更新を行いたい場合は、更新可能イベントを利用してください。更新可能イベントは識別イベントのIDが必要で、作成時はプロパティに入れてください。TEシステムはイベント名とイベントIDを識別対象として更新データを確定します。

 //The event property status is 3 after reporting, with the price being 100
TDUpdatableEvent updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");
ThinkingAnalyticsAPI.Track(updatableEvent);

//The event property status is 5 after reporting, with the price remaining the same
TDUpdatableEvent updatableEvent_new = new TDUpdatableEvent("UPDATABLE_EVENT", new Dictionary<string, object>{
    {"status", 5}
}, "test_event_id");
ThinkingAnalyticsAPI.Track(updatableEvent_new);

2.4 書き替えイベント

書き替えイベントは更新可能イベントと同じようで、書き替えイベントは過去データを最新のデータで上書きされるため、前のデータを削除し新しくデータを格納するように見られます。TEシステムはイベント名とイベントIDを識別対象として更新データを確定します。

// Instance: Assume the event name is OVERWRITE_EVENT when reporting an overwritable event
//The event property status is 3 after reporting, with the price being 100
TDOverWritableEvent overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");
ThinkingAnalyticsAPI.Track(overWritableEvent);

//The event property status is 5 after reporting, with the price deleted
TDOverWritableEvent overWritableEvent_new = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 5}
}, "test_event_id");
ThinkingAnalyticsAPI.Track(overWritableEvent_new);

2.5 共通イベントプロパティ

共通イベントプロパティは全てのイベント送信する際に付属されているプロパティとなります。プロパティの更新頻度により、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティがあります。

実際業務ニーズに応じて、共通イベントプロパティの設定を行なってください；通常イベント送信する前に、共通イベントプロパティを設定してくのはオススメです。

同じイベントに、共通イベントプロパティ、イベントカスタムプロパティ、プリセットプロパティのKeyは同じの場合は、以下の優先順位で値付けされます。カスタムプロパティ＞動的共通イベントプロパティ＞静的共通イベントプロパティ＞プリセットプロパティ。

2.5.1 静的共通イベントプロパティ

静的共通イベントプロパティは低頻度変化かつ全てのイベントの属しているプロパティ：例えばVIPレベル。setSuperPropertiesを利用して、静的共通イベントプロパティを設定したら、SDKはイベント収集時に設定されている共通イベントプロパティを当イベントのプロパティとして利用されます。

Dictionary<string, object> superProperties = new Dictionary<string, object>(){ 
    {"vip_level", 2}
};
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

静的共通イベントプロパティはキャッシュに保存されるため、APPを起動するたびに呼び出す必要はありません。もしそのプロパティが存在されているのであれば、新たに設定するプロパティは元のプロパティ値を書き替えされます；もし以前そのプロパティが存在しない場合は、新規プロパティとして作成されます。プロパティ設定以外にはAPI利用で静的共通イベントプロパティを管理できます。

//clear super property named 'CHANNEL'
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");
//clear all super properties
ThinkingAnalyticsAPI.ClearSuperProperties();
//get all super properties
ThinkingAnalyticsAPI.GetSuperProperties();

2.5.2 動的共通イベントプロパティ

動的共通イベントプロパティは高頻度変化かつ全てのイベントに属しているプロパティです。（例えばコインの数量）動的共通イベントプロパティを設定するには、新しい動的共通イベントプロパティクラスIDynamicSuperPropertiesを作成して、public Dictionary<string, object> GetDynamicSuperProperties() の方法を複写し、このメソッドの戻り値は、設定が必要な動的共通イベントプロパティです。SetDynamicSuperPropertiesを呼び出して共通プロパティオブジェクトを入れます。

// 1. implement dynamic properties interface, this is an example of setting the dynamic change of gold coins
public class DynamicProp : IDynamicSuperProperties
{    
    int coin = 0;
    public Dictionary<string, object> GetDynamicSuperProperties()
    {  
         coin++;
         return new Dictionary<string, object>() {
             {"coin",coin}
         };
    }
}
// 2. set dynamic properties
ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());

2.6 イベント時間記録

イベントの経過時間を記録したい場合は、timeEventを呼び出して計算可能です。計算したいイベント名称を設定し、該当イベントが送信される際に、自動的にイベントプロパティに#durationのプロパティを追加され、経過時間を記録されます。単位は秒です。

注意：一つイベントに対しては一個の時間経過計算タスクのみつけることが可能です。

//The following instance has recorded the time the user spent on a certain product page
//The user enters the product page and starts the timing
ThinkingAnalyticsAPI.TimeEvent("stay_shop");
/**do someting
    .......
**/
//the timing would end when the user leaves the product page. "stay_shop" event would carry#duration, a property representing event duration. 
ThinkingAnalyticsAPI.Track("stay_shop");

ユーザープロパティ

TEでユーザープロパティを設定するAPIはUserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppend、UserUniqAppend。

3.1 UserSet

一般的にユーザープロパティ設定はUserSetを用いて設定できます。この呼び出しを利用して元のプロパティ値を書き替えされます。元のプロパティ値がない場合は、新規作成になります。データタイプは格納されたデータタイプと一致します。以下は例：

//the username now is TA
ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
//the username now is TE
ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>(){{"user_name", "TE"}});

3.2 UserSetOnce

もしユーザープロパティは一回設定の上で変更がない場合は、UserSetOnceを用いて設定できます。この呼び出しは値のある際に書き替えを行いません。

//first_payment_time is '2018-01-01 01:23:45.678'
ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>(){
    {"first_payment_time","2018-01-01 01:23:45.678"}
});
 //first_payment_time is '2018-01-01 01:23:45.678' as before
ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>(){
    {"first_payment_time","2018-12-31 01:23:45.678"}
});

3.3 UserAdd

もし数値型のプロパティで累積計算を行いたい場合は、UserAddを用いて設定できます。この呼び出しは値のない際に自動で0を付与した上で計算されます。"-"値で計算することも可能で、例：累積課金金額

//current total_revenue is 30
ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>(){
    {"total_revenue",30}
});
//current total_revenue is 678
ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>(){
    {"total_revenue",648}
})

設定したプロパティは文字列で、Value は数値のみとなります。

3.4 UserUnset

ユーザープロパティをリセットしたい場合は、UserUnsetを用いて設定できます。このプロパティはクラスター内で作成されていない場合は、UserUnsetはそのプロパティを作成しません。

// delete a user property named 'userPropertyName'
ThinkingAnalyticsAPI.UserUnset("userPropertyName");
// delete some user properties as List
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");

ThinkingAnalyticsAPI.UserUnset(listProps);

送信値はクリアされたプロパティのkey値となります

3.5 UserDelete

ユーザーを削除したい場合はUserDeleteを用いて設定できます。削除したら当ユーザーのユーザープロパティはクエリできなくなりますが、当ユーザーが生成したイベントデータはクエリできます。

ThinkingAnalyticsAPI.UserDelete();

3.6 UserAppend

UserAppend を用いてArray型のユーザープロパティを追加できます。

List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
// call UserAppend to add elements for user property user_list. In this case, mon-existing elements would be newly created
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>{
    {"user_list", stringList }
});

3.7 UserUniqAppend

UserUniqAppendを用いてlist型のユーザープロパティを追加できます。

UserUniqAppendは重複排除でユーザープロパティを追加されますが、userappendは重複排除しません。

//the property value of user_list is ["apple"，"ball"]
List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>{
    {"user_list", stringList}
});

List<string> stringList1 = new List<string>();
stringList1.Add("apple");
stringList1.Add("cube");
//the property value of user_list is ["apple","apple","ball","cube"]
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>{
    {"user_list", stringList1}
});
//the property value of user_list is ["apple","ball","cube"]
ThinkingAnalyticsAPI.UserUniqAppend(new Dictionary<string, object>{
    {"user_list", stringList1}
});

暗号化機能

v2.4.0 以降のバージョンは、SDKデータ送信にAES+RSA暗号化を対応できるようになりました。データの暗号化処理はクライアントとサーバと合わせて処理となります、詳しくは弊社担当スタッフまでご連絡ください。

TokenオブジェクトのenableEncryptプロパティをtrueに設定の上、デフォルトバージョン番号と公開鍵を設定します。

ThinkingAnalyticsAPI.Token token = new ThinkingAnalyticsAPI.Token(appId, serverUrl);
token.enableEncrypt = true;
token.encryptVersion = 1;
token.encryptPublicKey = "YOUR_ENCRYPT_PUBLIC_KEY";
ThinkingAnalyticsAPI.StartThinkingAnalytics(token);

その他機能

5.1 デバイスIDを取得

getDeviceIdを呼び出して、デバイスIDを取得できます：您可以通过调用 GetDeviceId 来获取设备 ID：

ThinkingAnalyticsAPI.GetDeviceId();

5.2 デフォルトタイムゾーン設定

デフォルトでSDKは本デバイスの表示時間をイベント発生時間として送信されます。デフォルトタイムゾーンを指定することも可能です。

ThinkingAnalyticsAPI.Token token = new ThinkingAnalyticsAPI.Token(appId, serverUrl);
token.timezone = ThinkingAnalyticsAPI.TATimeZone.UTC;
ThinkingAnalyticsAPI.StartThinkingAnalytics(token);

タイムゾーン指定したら、本デバイスのタイムゾーンのデータが破棄されます。もし本デバイスのタイムゾーンを保留したい場合は、別途イベントにカスタムプロパティを追加してください。

5.3 時間校正

SDK デフォルトで本デバイス時間をイベント発生時間として利用されますが、ユーザーが手動でデバイスの時間を修正したりするとそのまま修正後の時間として送信されますため、分析に支障が出てしまいます。時間校正を利用して、イベント発生時間の正確性を保つことができます。TEシステムはtimestampと NTPの二つの時間校正方法を対応しております。

• サーバ側から同期された現在のtimestampを使ってSDKの時間を校正できます。その後、全て時間未指定の呼び出し（イベントデータとユーザープロパティ設定）は校正後の時間を発生時間として使われます。

// 1585633785954 is the current unix time stamp, with the unit being millisecond; 
// the corresponding Beijing time is 2020-03-31 13:49:45
ThinkingAnalyticsAPI.calibrateTime(1585633785954);

• NTPサーバアドレス設定でSDKはNTPサービスの当地時間を取得し利用されます。デフォルトで時間オーバー（3秒）して取得できなかった場合は、ローカル時間として送信されます。

// use the NTP service of Apple Inc for time calibration 
ThinkingAnalyticsAPI.calibrateTimeWithNtp("time.apple.com");

1、NTPサービスで時間校正を行うには不安定性があり、timestampを推奨しております。

2、NTPサービスを利用する場合は、ネット環境が良好で、ユーザーデバイスは素早くサーバ時間を取得可能できるのを保つ必要があります。

5.4 即時データ送信

一般的には一定の時間間隔で、または一定のデータ量を貯めてからデータ送信となりますが、特定のイベントデータを即時にデータ送信したい場合はflushを用いて設定できます。

ThinkingAnalyticsAPI.Flush();

5.5 国/地域コード取得

国/地域コード取得したい場合はgetLocalRegionを用いて取れます。在某些业务场景下，如果您需要知道用户设备的国家/地区代码，可以通过GetLocalRegion来获取

ThinkingAnalyticsAPI.GetLocalRegion();