Flutter - Advanced

ユーザーID設定

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

1.1 ゲストID設定

::: Tips

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

:::

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

//set distinct ID as Thinker
ta.identify("Thinker");

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

//return distinct ID
String distinctId = await ta.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
ta.login("TE");

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

1.3 アカウントIDをクリア

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

ta.logout();

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

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

イベント送信

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

2.1 通常イベント

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

例：アイテム購入

ta.track('pruoduct_buy', properties: <String, dynamic>{'product_name': 'アイテム名'});

2.2 初回イベント

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

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

var properties = {'key': 'value'};
var firstModel = TrackFirstEventModel('device_activation', '', properties);
ta.trackEventModel(firstModel);

もしデバイス以外の主体で初回判断したい場合は、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.
var properties = {'key': 'value'};
var firstModel = TrackFirstEventModel('account_activation', 'TE', properties);
ta.trackEventModel(firstModel);

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

2.3 更新可能イベント

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

//The event property status is 3 after reporting, with the price being 100
var properties = {
  'status': 3,
  'price': 100
};
var updateModel = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', properties);
ta.trackEventModel(updateModel);

//The event property status is 5 after reporting, with the price remaining the same
var properties_new = {
  'status': 5
};
var updateModel_new = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', properties_new);
ta.trackEventModel(updateModel_new);

2.4 書き替えイベント

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

// The event property status is 3 after reporting, with the price being 100
var properties = {
    'status': 3,
    'price': 100
};
var overwriteModel = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', properties);
ta.trackEventModel(overwriteModel);

// The event property status is 5 after reporting, with the price deleted
var properties_new = {
    'status': 5
};
var overwriteModel_new = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', properties_new);
ta.trackEventModel(overwriteModel_new);

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

共通イベントプロパティは全てのイベント送信する際に付属されているプロパティとなります。プロパティの更新頻度により、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティがあります。実際業務ニーズに応じて、共通イベントプロパティの設定を行なってください；通常イベント送信する前に、共通イベントプロパティを設定しておいてください。同じイベントに、共通イベントプロパティ、イベントカスタムプロパティ、プリセットプロパティのKeyは同じの場合は、以下の優先順位で値付けされます。

カスタムプロパティ＞動的共通イベントプロパティ＞静的共通イベントプロパティ＞プリセットプロパティ

2.5.1 静的共通プロパティ

重要のプロパティに対しては：ユーザーのチャンネル、ニックネーム、IDなどはすべてのイベントの中に付属したい場合は、 setSuperPropertiesを利用して、静的共通イベントプロパティを設定してください

Map<String, dynamic> superProperties = {
  'vip_level': 2
};
ta.setSuperProperties(superProperties);

静的共通イベントプロパティはキャッシュに格納されるため、アプリを起動するたびに呼び出す必要はありません。該当プロパティがすでに存在する場合は元の値を上書きします。該当プロパティが以前に存在しなかった場合、新しいプロパティが作成されます。プロパティ設定以外では、その他API利用で静的共通イベントプロパティの設定が可能です。

//clear a certain super property
ta.unsetSuperProperty('SUPER_LIST');
//clear all certain super properties
ta.clearSuperProperties();
//obtain all certain super properties
ta.getSuperProperties();

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

動的共通イベントプロパティは高頻度変化かつ全てのイベントに属しているプロパティです。（例えばコインの数量）setDynamicSuperPropertiesTrackerを利用し動的共通イベントプロパティを設定した後で、SDKはイベント収集時に自動でgetDynamicSuperPropertiesのプロパティを取得し、イベント送信されます。

ta.setDynamicSuperProperties((){
  return <String, dynamic> {
    'DYNAMIC_DATE': DateTime.now().toUtc(),
  };
});

動的共通プロパティは自動集取イベントに対応されていません。

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
ta.timeEvent('stay_shop');
// do some thing...
//the timing would end when the user leaves the product page. "stay_shop" event would carry#duration, a property representing event duration. 
ta.track("stay_shop");

ユーザープロパティ

TEでユーザープロパティを設定するAPIは userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppend

3.1 userSet

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

ta.userSet(<String, dynamic>{'user_name': 'TA'});  //the username now is TA
ta.userSet(<String, dynamic>{'user_name': 'TE'});  //the username now is TE

プロパティのデータ形式はイベントプロパティと一致する必要があります。

3.2 userSetOnce

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

//first_payment_time is 2018-01-01 01:23:45.678
ta.userSetOnce(<String, dynamic>{'first_payment_time': '2018-01-01 01:23:45.678'});
//first_payment_time is still 2018-01-01 01:23:45.678
ta.userSetOnce(<String, dynamic>{'first_payment_time': '2018-12-31 01:23:45.678'});

3.3 userAdd

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

//in this case, the total_revenue is 30
ta.userAdd(<String, num>{ 'total_revenue': 30});
//in this case, the total_revenue is 678
ta.userAdd(<String, num>{ 'total_revenue': 648});

3.4 userUnset

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

ta.userUnset('USER_INT');

userUnset: 送信される値はクリアされたKey valueとなります。

3.5 userDelete

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

ta.userDelete();

3.6 userAppend

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

ta.userAppend(<String, List>{
  'USER_LIST': ['apple','ball'],
});

3.7 userUniqAppend

userUniqAppendを利用して、Array (List)型のユーザーデータにユニークエレメントを追加できます。userUniqAppendインターフェースは追加されたユーザープロパティを重複排除され、userAppendは重複排除しませんので、ユーザープロパティは重複される可能性があります。

//in this case, the property value of user_list is ["apple"，"ball"]
ta.userAppend(<String, List>{ 'user_list': ['apple','ball']});
//in this case, the property value of user_list is ["apple","apple","ball","cube"]
ta.userAppend(<String, List>{ 'user_list': ['apple','cube']});
//in this case, the property value of user_list is ["apple"，"ball","cube"]
ta.useUniqrAppend(<String, List>{ 'user_list': ['apple','cube']});

送信データの暗号化対応

SDKは暗号化機能に対応しており、クライアントはAES + RSAでデータを暗号化処理してから、サーバ側で暗号化を解けます。クライアントとサーバ両方の作業があり、詳しくはTDスタッフまでお問い合わせください。 SDK初期設定する時に、データ送信暗号化機能を有効にできます。

var sKey = TASecretKey();
//Configure key information such as version number and public key
sKey.publicKey =
    "xxx";
sKey.version = 1;
sKey.symmetricEncryption = "AES";
sKey.asymmetricEncryption = "RSA";
ThinkingAnalyticsAPI.getInstance(
    'APP_ID',
    'server_url',
    enableEncrypt: true,
    secretKey: sKey);

その他機能

5.1 デバイスIDを取得

SDKが初期設定完了したら、自動でデバイスIDが生成され、ローカルキャッシュに保存されます。同一APP/gameにおいては、一台のデバイスのデバイスIDは不変でgetDeviceIdを利用して、デバイスIDの取得ができます。

String deviceId = await ta.getDeviceId();

5.2 タイムゾーン

SDK デフォルトで本デバイス時間をイベント発生時間として利用されます。プロダクトが複数のタイムゾーンでリリースされた場合は、timeZoneを同時に送信してタイムゾーン設定できます。timeZoneはタイムゾーン文字列で、UTC, Asia/Shanghaiなどとなります。

ThinkingAnalyticsAPI.getInstance('APP_ID','server_url',timeZone:'UTC');

タイムゾーンすると、デバイス本体のタイムゾーン情報が破棄されます。デバイス本体のタイムゾーンが保留したい場合は、イベントにプロパティ設定しておいてください。

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