Cocos2d-x Advanced

アカウントID設定

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

1.1 ゲストID設定

TIP

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

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

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

// set distinct ID as Thinker
TDAnalytics::identify("Thinker");

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

//Return distinct ID
string distinctId = TDAnalytics::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
TDAnalytics::login("TE");

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

1.3 アカウントIDをクリア

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

TDAnalytics::logout();

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

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

イベント送信

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

2.1 通常イベント

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

例：アイテム購入

TDJSONObject eventProperties;
eventProperties.setString("product_name", "アイテム名");
TDAnalytics::track("product_buy",eventProperties);

2.2 初回イベント

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

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

TDJSONObject jsonObject;
jsonObject.setString("key","value");
TDFirstEvent *firstEvent = new TDFirstEvent("device_activation",jsonObject);
TDAnalytics::track(firstEvent);

もしデバイス以外で初回判断したい場合は、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.
TDJSONObject jsonObject;
jsonObject.setString("key","value");
TDFirstEvent *firstEvent = new TDFirstEvent("account_activation",jsonObject);
firstEvent->setFirstCheckId("TE");
TDAnalytics::track(firstEvent);

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

2.3 更新可能イベント

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

//The event property status is 3 after reporting, with the price being 100
TDJSONObject jsonObject;
jsonObject.setNumber("status", 3);
jsonObject.setNumber("price", 100);
TDUpdatableEvent *updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject,"test_event_id");
TDAnalytics::track(updatableEvent);

//The event property status is 5 after reporting, with the price remaining the same
TDJSONObject jsonObject_new;
jsonObject_new.setNumber("status", 5);
TDUpdatableEvent *updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject_new,"test_event_id");
TDAnalytics::track(updatableEvent);

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 TDJSONObject jsonObject;
jsonObject.setNumber("status", 3);
jsonObject.setNumber("price", 100);
TDOverWritableEvent *overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT",jsonObject,"test_event_id");
TDAnalytics::track(overWritableEvent);

//The event property status is 5 after reporting, with the price deleted
TDJSONObject jsonObject_new;
jsonObject_new.setNumber("status", 5);
TDOverWritableEvent overWritableEvent_new =  new TDOverWritableEvent("OVERWRITABLE_EVENT",jsonObject,"test_event_id");
TDAnalytics::track(overWritableEvent_new);

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

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

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

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

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

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

 TDJSONObject superProperties;
 userProperties.setNumber("level",2);
 TDAnalytics::setSuperProperties(superProperties);

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

//clear a certain super property
TDAnalytics::unsetSuperProperty("CHANNEL");
//clear all certain super properties
TDAnalytics::clearSuperProperties();
//get all certain super properties
TDAnalytics::getSuperProperties();

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

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

//frequency update of gold coin quantity 
int coin = 0
TDJSONObject dynamicProperties()
{
    coin++;
    TDJSONObject obj;
    obj.setNumber("coin",coin);
    return obj;
}
TDAnalytics::setDynamicSuperProperties(dynamicProperties);

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
TDAnalytics::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. 
TDAnalytics::track("stay_shop");

ユーザープロパティ

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

3.1 userSet

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

//the username now is TA
TDJSONObject properties;
properties.setString("username", "TA");
TDAnalytics::userSet(properties);
//the userName now is TE
TDJSONObject newProperties;
newProperties.setString("username", "TE");
TDAnalytics::userSet(newProperties);

3.2 userSetOnce

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

//first_payment_time is 2018-01-01 01:23:45.678
TDJSONObject userProperties;
userProperties.setString("first_payment_time","2018-01-01 01:23:45.678");
TDAnalytics::userSetOnce(userProperties);

//first_payment_time is still 2018-01-01 01:23:45.678
TDJSONObject newUserProperties;
newUserProperties.setString("first_payment_time","2018-12-31 01:23:45.678");
TDAnalytics::userSetOnce(newUserProperties);

3.3 userAdd

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

//in this case, the total_revenue is 30
TDJSONObject userProperties;
userProperties.setNumber("total_revenue",30);
TDAnalytics::userAdd(userProperties);

//in this case, the total_revenue is 678
TDJSONObject newUserProperties;
newUserProperties.setNumber("total_revenue",648);
TDAnalytics::userAdd(newUserProperties);

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

3.4 userUnset

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

TDAnalytics::userUnset("coin");

受信される値はクリアされたプロパティのKey値となります。

3.5 userDelete

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

TDAnalytics::userDelete();

3.6 userAppend

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

TDJSONObject userProperties;
vector<string> listValue;
listValue.push_back("apple");
listValue.push_back("ball");
userProperties.setList("user_list",listValue);
TDAnalytics::userAppend(userProperties);

3.7 user_uniqueAppend

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

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

// list is the value of user property user_list, JSONArray type
//in this case, the property value of user_list is ["apple"，"ball"]
TDJSONObject properties;
vector<string> dataArray;
dataArray.push_back("apple");
dataArray.push_back("ball");
properties.setList("user_list",dataArray);
TDAnalytics::userAppend(properties);

//in this case, the property value of user_list is ["apple","apple","ball","cube"]
TDJSONObject properties1;
vector<string> dataArray1;
dataArray1.push_back("apple");
dataArray1.push_back("cube");
properties1.setList("user_list",dataArray1);
TDAnalytics::userAppend(properties1);

 //in this case, the property value of user_list is ["apple"，"ball","cube"]
TDAnalytics::user_uniqAppend(properties1);

その他機能

4.1 デバイスIDを取得

getDeviceIdを呼び出して、デバイスIDを取得できます：

TDAnalytics::getDeviceId();

// TDAnalytics::identify(TDAnalytics::getDeviceId());

4.2 時間校正

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

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

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

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

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

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

4.3 即時データ送信

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

TDAnalytics::flush();

4.4 暗号化機能

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

setEnableEncrypt呼び出して暗号化処理を有効にし、setSecretKeyでRSAの公開キー情報を設定できます。

Config config1(APPID,SERVER_URL);
config1.setEnableEncrypt(true);
config1.setSecretKey(SecretKey(SecretKeyVersion, _SecretKey));
TDAnalytics::init(config1);