Unreal - Advanced

アカウントID設定

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

1.1 ゲストID設定

TIP

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

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

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

// set distinct ID as Thinker
UTDAnalytics::Identify("Thinker");

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

FString distinctId = UTDAnalytics::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
UTDAnalytics::Login("TE");

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

1.3 アカウントIDをクリア

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

UTDAnalytics::Logout();

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

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

イベント送信

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

2.1 通常イベント

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

例：アイテム購入

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("product_name", "product name");
UTDAnalytics::Track("product_buy",Properties);

2.2 初回イベント

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

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

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("key", "value");
UTDAnalytics::TrackFirst("device_activation",Properties);

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

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("key", "value");
UTDAnalytics::TrackFirstWithId("account_activation", Properties,"TE");

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

2.3 更新可能イベント

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

 //The event property status is 3 after reporting, with the price being 100 TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetNumberField("status",3);
Properties->SetNumberField("price",100);
UTDAnalytics::TrackUpdate("UPDATABLE_EVENT", Properties,"test_event_id");

//The event property status is 5 after reporting, with the price remaining the same
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetNumberField("status",5);
UTDAnalytics::TrackUpdate("UPDATABLE_EVENT",NewProperties,"test_event_id");

2.4 書き替えイベント

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

 //The event property status is 3 after reporting, with the price being 100 TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject); TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetNumberField("status",3);
Properties->SetNumberField("price",100);
UTDAnalytics::TrackOverwrite("OVERWRITE_EVENT", Properties,"test_event_id");

//The event property status is 5 after reporting, with the price remaining the same
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetNumberField("status",5);
UTDAnalytics::TrackOverwrite("OVERWRITE_EVENT",NewProperties,"test_event_id")

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

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

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

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

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

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

TSharedPtr<FJsonObject> SuperProperties = MakeShareable(new FJsonObject);
SuperProperties->SetNumberField("vip_level",2);
UTDAnalytics::SetSuperProperties(SuperProperties);

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

//get all certain super properties
TSharedPtr<FJsonObject> SuperProperties = UTDAnalytics::GetSuperProperties();

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

動的共通イベントプロパティは高頻度変化かつ全てのイベントに属しているプロパティです。（例えばコインの数量）SetDynamicSuperPropertiesTracker を介して動的共通プロパティを設定した後、SDK はイベントの収集時に動的共通イベントのプロパティを自動的に取得し、それらをトリガー イベントに追加されます。

static FString TDReturnDyldParams() {
    return "{\"dyld_property1\":\"value1\",\"dyld_property2\":\"value2\"}";
}
void UMyDemoWidget::callSetDynamicSuperPropertiesFunction(){
    // since V1.5.0
    UTDAnalytics::dynamicPropertiesMap.insert(pair<FString,FString(*)(void)>("inset your appid" ,&TDReturnDyldParams));
    // since V1.5.0
    UTDAnalytics::SetDynamicSuperProperties(this, &UMyDemoWidget::TDReturnDyldParams, "your appid");
}

2.6 イベント時間記録

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

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

//The following instance has recorded the time the user spent on a certain product page
UTDAnalytics::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. 
UTDAnalytics::Track("stay_shop", "");

注意：Windows/MacOS は現在、イベント期間の記録を対応していません。

ユーザープロパティ

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

3.1 UserSet

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

//the username now is TA
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("user_name", "TA");
UTDAnalytics::UserSet(Properties);
//the username now is TE
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("user_name", "TE");
UTDAnalytics::UserSet(NewProperties);

3.2 UserSetOnce

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

//first_payment_time is 2018-01-01 01:23:45.678
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("first_payment_time","2018-01-01 01:23:45.678");
UTDAnalytics::UserSetOnce(Properties);
//first_payment_time is still 2018-01-01 01:23:45.678
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("first_payment_time","2018-12-31 01:23:45.678");
UTDAnalytics::UserSetOnce(NewProperties);

3.3 UserAdd

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

//in this case, the total_revenue is 30
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetNumberField("total_revenue",30);
UTDAnalytics::UserAdd(Properties);
//in this case, the total_revenue is 678
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetNumberField("total_revenue",648);
UTDAnalytics::UserAdd(NewProperties);

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

3.4 UserDelete

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

UTDAnalytics::UserDelete();

3.5 UserUnset

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

UTDAnalytics::UserUnset("userPropertyName");

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

3.6 UserAppend

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

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
TArray< TSharedPtr<FJsonValue> > DataArray;
DataArray.Add(MakeShareable(new FJsonValueString("apple")));
DataArray.Add(MakeShareable(new FJsonValueString("ball")));
Properties->SetArrayField("user_list", DataArray);
UTDAnalytics::UserAppend(Properties);

3.7 UserUniqAppend

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

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

// list is the value of user property user_list, JSONArray type
//in this case, the property value of user_list is ["apple"，"ball"]
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
TArray< TSharedPtr<FJsonValue> > DataArray;
DataArray.Add(MakeShareable(new FJsonValueString("apple")));
DataArray.Add(MakeShareable(new FJsonValueString("ball")));
Properties->SetArrayField("user_list", DataArray);
UTDAnalytics::UserAppend(Properties);

//in this case, the property value of user_list is ["apple","apple","ball","cube"]
TSharedPtr<FJsonObject> Properties1 = MakeShareable(new FJsonObject);
TArray< TSharedPtr<FJsonValue> > DataArray1;
DataArray1.Add(MakeShareable(new FJsonValueString("apple")));
DataArray1.Add(MakeShareable(new FJsonValueString("cube")));
Properties->SetArrayField("user_list", DataArray1);
UTDAnalytics::UserAppend(Properties1);

//in this case, the property value of user_list is ["apple"，"ball","cube"]
UTDAnalytics::UserUniqueAppend(Properties1);

その他機能

4.1 デバイスIDを取得

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

FString deviceId = UTDAnalytics::GetDeviceId();

4.2 時間校正

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
UTDAnalytics::CalibrateTime(1585633785954);

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

//use the NTP service of Apple Inc for time calibration 
UTDAnalytics::CalibrateTimeWithNtp("time.apple.com");

1、NTPサービスで時間校正を行うには不安定性があり、timestampを推奨しております。
2、NTPサービスを利用する場合は、ネット環境が良好で、ユーザーデバイスは素早くサーバ時間を取得可能できるのを保つ必要があります。

4.3 即時データ送信

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

UTDAnalytics::Flush();