応用ガイド
1. ユーザーIDの設定
SDKインスタンスは、デフォルトでランダムなUUIDを各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログイン状態のときの識別IDとして使われます。なお、ゲストIDは、ユーザーがAppを再インストールしたり、デバイスを変更したりすると変わります。
1.1 ゲストIDの設定
通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。
ゲストIDを置き換える必要がある場合は、SDKの初期化が完了した直後に呼び出してください。不要なアカウントが生成されないよう、複数回呼び出さないでください
Appで独自のゲストID管理体系を持っている場合は、SetDistinctIdを呼び出してゲストIDを設定できます：
// ゲストIDをThinkerに設定
TDAnalytics.SetDistinctId("Thinker");
現在のゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます：
//ゲストIDを返す
TDAnalytics.GetDistinctId();
1.2 アカウントIDの設定
ユーザーがログインする際にLoginを呼び出してユーザーのアカウントIDを設定できます。AEプラットフォームはアカウントIDを識別IDとして使用し、設定したアカウントIDはLogoutを呼び出すまで保持されます。Loginを複数回呼び出すと、以前のアカウントIDが上書きされます。
// ユーザーのログイン固有識別子。このデータは送信データの#account_idに対応し、この時点で#account_idの値はTA
TDAnalytics.Login("TA");
このメソッドはログインイベントを送信しません
1.3 アカウントIDのクリア
ユーザーがログアウトした後、Logoutを呼び出してアカウントIDをクリアできます。次にLoginを呼び出すまでは、ゲストIDが識別IDとして使用されます。
// アカウントIDをクリア
TDAnalytics.Logout();
Logoutは、明示的なログアウトイベントが発生したとき（たとえばユーザーがアカウントを解約したとき）にのみ呼び出すことをお勧めします。アプリを閉じるときに呼び出す必要はありません。
このメソッドはログアウトイベントを送信しません
2. イベントの送信
SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。
2.1 通常イベント
Trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する場合を例にします：
Dictionary<string, Object> dic = new Dictionary<string, object>();
dic.Add("product_name", "商品名");
TDAnalytics.Track( "product_buy",dic);
2.2 初回イベント
初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。
Dictionary<string, object> dic = new Dictionary<string, object>();
dic.Add("key", "value");
TDFirstEvent firstEventModel = new TDFirstEvent("device_activation", dic);
TDAnalytics.Track(firstEventModel);
デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：
// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集
Dictionary<string, object> dic = new Dictionary<string, object>();
dic.Add("key", "value");
TDFirstEventModel firstEventModel = new TDFirstEventModel("device_activation", dic, "TA");
TDAnalytics.Track(firstEventModel);
注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。
2.3 更新可能イベント
更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
// 例：更新可能なイベントを送信。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
Dictionary<string, Object> dic = new Dictionary<string, object>();
dic.Add("price", 100);
dic.Add("status",3);
TDUpdatableEventModel updatableEventModel = new TDUpdatableEventModel("UPDATABLE_EVENT", dic, "updateEventId");
TDAnalytics.Track(updatableEventModel);
// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
Dictionary<string, Object> dic1 = new Dictionary<string, object>();
dic1.Add("status",5);
TDUpdatableEventModel updatableEventModel_new = new TDUpdatableEventModel("UPDATABLE_EVENT", dic1,"updateEventId");
TDAnalytics.Track(updatableEventModel_new);
2.4 上書き可能イベント
上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
// 例：上書き可能なイベントを送信。イベント名はOVERWRITABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
Dictionary<string, Object> dic = new Dictionary<string, object>();
dic.Add("price", 100);
dic.Add("status",3);
TDOverwritableEventModel overwritableEventModel = new TDOverwritableEventModel("OVERWRITABLE_EVENT", dic,"eventId");
TDAnalytics.Track(overwritableEventModel);
// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
Dictionary<string, Object> dic1 = new Dictionary<string, object>();
dic1.Add("status",5);
TDOverwritableEventModel overwritableEventModel_new = new TDOverwritableEventModel("OVERWRITABLE_EVENT", dic1,"eventId");
TDAnalytics.Track(overwritableEventModel_new);
2.5 共通イベントプロパティ
共通イベントプロパティとは、すべてのイベントで送信されるプロパティのことです。
2.5.1 静的共通イベントプロパティ
静的共通イベントプロパティとは、変化の頻度が低く、すべてのイベントに含まれるプロパティのことです（ユーザーの会員レベルなど）。setSuperPropertiesで静的共通イベントプロパティを設定すると、SDKはイベントの収集時に、設定された共通イベントプロパティをイベントのプロパティとして取得します。
Dictionary<string, object> superProperties = new Dictionary<string, object>();
superProperties["vip_level"] = 2;
TDAnalytics.SetSuperProperties(superProperties);
静的共通イベントプロパティはキャッシュに保存されるため、Appを起動するたびに呼び出す必要はありません。そのプロパティがすでに存在する場合は、再設定したプロパティで元のプロパティ値が上書きされます。そのプロパティが存在しない場合は、新しく作成されます。プロパティの設定以外にも、静的共通イベントプロパティを管理するためのAPIを提供しており、日常的な業務要件に対応できます。
//特定の共通イベントプロパティをクリア
TDAnalytics.UnsetSuperProperties("Channel");
//すべての共通イベントプロパティをクリア
TDAnalytics.ClearSuperProperties();
//すべての共通イベントプロパティを取得
var superProperties = TDAnalytics.GetSuperProperties();
2.5.2 動的共通イベントプロパティ
動的共通イベントプロパティは、頻繁に変化し、すべてのイベントに付与されるプロパティです（ユーザーのコイン数など）。SetDynamicSuperPropertiesで動的共通プロパティのクラスを設定すると、SDKはイベント収集時にプロパティを自動的に取得し、トリガーされたイベントに追加します。
static Dictionary<string, object> GetDynamicSuperProperties()
{
return new Dictionary<string, object> { { "coin", 10 } };
}
TDAnalytics.Init(config);
TDAnalytics.SetDynamicSuperProperties(GetDynamicSuperProperties);
2.6 イベントの所要時間の記録
あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。
//ユーザーが商品ページに入り、計測を開始
TDAnalytics.TimeEvent("stay_shop");
/**do someting
.......
**/
//ユーザーが商品ページを離れ、計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが付与されます
TDAnalytics.Track("stay_shop");
3. ユーザープロパティ
AEプラットフォームが対応しているユーザープロパティ設定APIは、UserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppendです。
3.1 UserSet
一般的なユーザープロパティは、UserSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は、新しく作成されます。
//この時点でuser_nameはTA
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
//この時点でuser_nameはAE
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "AE"}});
3.2 UserSetOnce
送信するユーザープロパティを一度だけ設定すればよい場合は、UserSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます：
//first_pay_timeは2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){{"first_pay_time","2018-01-01 01:23:45.678"}});
//first_pay_timeは引き続き2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){{"first_pay_time","2018-12-31 01:23:45.678"}});
3.3 UserAdd
数値型のプロパティを送信する場合は、UserAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。
//この時点でtotal_revenueは30
TDAnalytics.UserAdd(new Dictionary<string, object>(){{"total_revenue",30}});
//この時点でtotal_revenueは678
TDAnalytics.UserAdd(new Dictionary<string, object>(){{"total_revenue",648}});
設定するプロパティのkeyは文字列で、Valueには数値のみ指定できます。
3.4 UserUnset
ユーザーの特定のプロパティをリセットする場合は、UserUnsetを呼び出して、そのユーザーの指定したユーザープロパティの値をクリアできます。
TDAnalytics.UserUnset("nickname");
渡す値は、クリアするプロパティのKey値です。
3.5 UserDelete
あるユーザーを削除する場合は、UserDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。
TDAnalytics.UserDelete();
3.6 UserAppend
UserAppendを呼び出して、List型のユーザープロパティに要素を追加できます：
Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list6 = new List<string>();
list6.Add("true");
list6.Add("test");
dictionary.Add("arrkey4", list6);
TDAnalytics.UserAppend( dictionary);
3.7 UserUniqAppend
UserUniqAppendを呼び出して、Array (List)型のユーザーデータに一意の要素を追加できます。UserUniqAppendインターフェースは追加するユーザープロパティの重複を排除しますが、UserAppendインターフェースは重複を排除しないため、ユーザープロパティに重複が生じる場合があります。
//この時点でuser_listのプロパティ値は["apple"，"ball"]
Dictionary<string, Object> dic = new Dictionary<string, object>();
List<string> list = new List<string>();
list.Add("apple");
list.Add("ball");
dic.Add("user_list", list);
TDAnalytics.UserAppend(dic);
//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
Dictionary<string, Object> dic1 = new Dictionary<string, object>();
List<string> list1 = new List<string>();
list1.Add("apple");
list1.Add("cube");
dic1.Add("user_list", list1);
TDAnalytics.UserAppend(dic1);
//この時点でuser_listのプロパティ値は["apple"，"ball","cube"]
Dictionary<string, Object> dic2 = new Dictionary<string, object>();
List<string> list2 = new List<string>();
list2.Add("apple");
list2.Add("cube");
dic2.Add("user_list", list2);
TDAnalytics.UserUniqAppend(dic2);
4. 暗号化機能
v2.0.0-beta.1以降、SDKはAES+RSAによるデータの暗号化に対応しています。データ暗号化機能はクライアントとサーバーの連携が必要です。具体的な使用方法については、カスタマーサクセス担当者にお問い合わせください。
TDConfig config = new TDConfig();
config.AppId = appid;
config.ServerUrl = server_url;
config.EnableEncrypt = true;
config.Version = 1;
config.PublicKey = "publickKey";
TDAnalytics.Init(config);
5. その他の機能
5.1 SDKログの出力
// 有効にすると、プロジェクトのルートディレクトリにあるta_event_log.txtファイルでログを確認できます
TDAnalytics.EnableLogType(TDLogType.LogTxt);
5.2 プリセットプロパティの説明
| プロパティ名 | 画面表示名 | プロパティタイプ | 説明 |
|---|---|---|---|
| #ip | IPアドレス | テキスト | ユーザーのIPアドレス。AEはこれを基にユーザーの位置情報を取得します |
| #country | 国 | テキスト | ユーザーの所在国。IPアドレスに基づいて生成されます |
#country_code | 国コード | テキスト | ユーザーの所在国の国コード(ISO 3166-1 alpha-2、つまり大文字の英字2文字)。IPアドレスに基づいて生成されます |
| #province | 省 | テキスト | ユーザーの所在する省・州。IPアドレスに基づいて生成されます |
| #city | 都市 | テキスト | ユーザーの所在都市。IPアドレスに基づいて生成されます |
| #os | OS | テキスト | MacOS、Windowsなど |
| #device_id | デバイスID | テキスト | ユーザーのデバイスID |
#lib | SDKタイプ | テキスト | 接続したSDKのタイプ。Android、iOSなど |
| #lib_version | SDKバージョン | テキスト | 接続したSDKのバージョン |
5.3 時間の校正
SDKはデフォルトで端末のローカル時間をイベント発生時間として使用します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、時間の校正によってイベント発生時間の正確さを確保できます。タイムスタンプによる時間校正方法を提供しています。
- サーバーから取得した現在のタイムスタンプを使用して、SDKの時間を補正できます。以降、時間を指定していないすべての呼び出し（イベントデータやユーザープロパティの設定操作を含む）では、補正後の時間が発生時間として使用されます。
// 1585633785954は現在のunixタイムスタンプ（単位はミリ秒）で、北京時間2020-03-31 13:49:45に相当します
TDAnalytics.CalibrateTime(1585633785954);
- 自動時間校正を設定することもできます。設定すると、SDKはconfigインターフェースから現在時刻の取得を試み、SDKの時間を校正します。正しい結果が返されなかった場合は、以降はローカル時間でデータを送信します。
TDConfig config = new TDConfig();
config.AppId = appid;
config.ServerUrl = server_url;
config.EnableAutoCalibrated = true;
TDAnalytics.Init(config);
5.4 データの即時送信
業務シナリオによっては、データをすぐにAEサーバーに送信したい場合があります。その場合はflushインターフェースを呼び出します
TDAnalytics.Flush();
5.5 デバイスIDの取得
getDeviceIdを呼び出して、デバイスIDを取得できます：
TDAnalytics.GetDeviceId();
5.6 デフォルトタイムゾーンの設定
デフォルトでは、SDKはインターフェースを呼び出した時点の端末のローカル時間をイベント発生時間として送信します。デフォルトタイムゾーンを設定するインターフェースで既定のタイムゾーンを指定することもできます。これにより、すべてのイベントのイベント時間が設定したタイムゾーンに合わせられます：
TDConfig config = new TDConfig();
config.AppId = appid;
config.ServerUrl = server_url;
config.ZoneOffset = 5;
TDAnalytics.Init(config);
注意：指定したタイムゾーンでイベント時間を合わせると、デバイスのローカルタイムゾーンの情報は失われます。デバイスのローカルタイムゾーンの情報を保持する必要がある場合は、現時点ではイベントに関連プロパティを自分で追加する必要があります。