応用ガイド

最終更新 2026/10/03

1. ユーザーIDの設定

SDKインスタンスは、デフォルトでランダムなUUIDを各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログイン状態のときの識別IDとして使われます。なお、ゲストIDは、ユーザーがAppを再インストールしたり、デバイスを変更したりすると変わります。

1.1 ゲストIDの設定

ヒント

通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。

ゲストIDを置き換える必要がある場合は、SDKの初期化が完了した直後に呼び出してください。不要なアカウントが生成されないよう、複数回呼び出さないでください

ゲームで各ユーザーに独自のゲストID管理体系がある場合は、setDistinctIdを呼び出してゲストIDを設定できます：

// ゲストIDをThinkerに設定
TDAnalytics::setDistinctId("Thinker");

現在のゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます：

//ゲストIDを返す
string distinctId = 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として使われます。

TDAnalytics::logout();

logoutは、明示的なログアウトイベントのときに呼び出すことを推奨します。たとえば、ユーザーがアカウントからログアウトする操作を行ったときにのみ呼び出し、Appを閉じるときに呼び出す必要はありません。

このメソッドはログアウトイベントを送信しません

2. イベントの送信

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");
TDFirstEventModel *firstEvent = new TDFirstEventModel("device_activation", jsonObject);
TDAnalytics::track(firstEvent);

デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：

// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集します
TDJSONObject jsonObject;
jsonObject.setString("key","value");
TDFirstEventModel *firstEvent = new TDFirstEventModel("account_activation", jsonObject);
firstEvent->setFirstCheckId("TA");
TDAnalytics::track(firstEvent);

注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。

2.3 更新可能イベント

更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

// 例：更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDJSONObject jsonObject;
jsonObject.setNumber("status", 3);
jsonObject.setNumber("price", 100);
TDUpdatableEventModel *updatableEvent = new TDUpdatableEventModel("UPDATABLE_EVENT",jsonObject,"test_event_id");
TDAnalytics::track(updatableEvent);

// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDJSONObject jsonObject_new;
jsonObject_new.setNumber("status", 5);
TDUpdatableEventModel *updatableEvent_new = new TDUpdatableEventModel("UPDATABLE_EVENT",jsonObject_new,"test_event_id");
TDAnalytics::track(updatableEvent_new);

2.4 上書き可能イベント

上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

// 例：上書き可能なイベントを送信します。イベント名はOVERWRITABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDJSONObject jsonObject;
jsonObject.setNumber("status", 3);
jsonObject.setNumber("price", 100);
TDOverwritableEventModel *overWritableEvent = new TDOverwritableEventModel("OVERWRITABLE_EVENT",jsonObject,"test_event_id");
TDAnalytics::track(overWritableEvent);

// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDJSONObject jsonObject_new;
jsonObject_new.setNumber("status", 5);
TDOverwritableEventModel *overWritableEvent_new =  new TDOverwritableEventModel("OVERWRITABLE_EVENT", jsonObject_new,"test_event_id");
TDAnalytics::track(overWritableEvent_new);

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

共通イベントプロパティとは、すべてのイベントで送信されるプロパティのことです。プロパティの更新頻度に応じて、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティに分けられます。具体的な業務シナリオの要件に応じて、異なる共通イベントプロパティの設定方法を選択できます。イベントを送信する前に、共通イベントプロパティを設定しておくことを推奨します。同じイベントで、共通イベントプロパティ、イベントのカスタムプロパティ、プリセットプロパティのKeyが同じ場合は、次の優先順位で値が設定されます：カスタムプロパティ>動的共通イベントプロパティ>静的共通イベントプロパティ>プリセットプロパティ。

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

静的共通イベントプロパティとは、変化の頻度が低く、すべてのイベントに含まれるプロパティのことです（ユーザーの会員レベルなど）。setSuperPropertiesで静的共通イベントプロパティを設定すると、SDKはイベントの収集時に、設定された共通イベントプロパティをイベントのプロパティとして取得します。

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

静的共通イベントプロパティはキャッシュに保存されるため、Appを起動するたびに呼び出す必要はありません。そのプロパティがすでに存在する場合は、再設定したプロパティで元のプロパティ値が上書きされます。そのプロパティが存在しない場合は、新しく作成されます。プロパティの設定以外にも、静的共通イベントプロパティを操作するためのAPIを提供しており、日常的な業務要件に対応できます。

// プロパティ名がCHANNELの共通プロパティをクリア
TDAnalytics::unsetSuperProperty("CHANNEL");
// すべての共通プロパティをクリア
TDAnalytics::clearSuperProperties();
// すべての共通プロパティを取得
TDAnalytics::getSuperProperties();

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

動的共通イベントプロパティとは、変化の頻度が高く、すべてのイベントに含まれるプロパティのことです（ユーザーのコイン数など）。setDynamicSuperPropertiesで動的共通プロパティのクラスを設定すると、SDKはイベントの収集時に動的共通イベントプロパティを自動的に取得し、トリガーされたイベントに追加します。

// 動的共通プロパティを設定し、イベント送信時にイベント発生時点の値を動的に取得
int coin = 0;
TDJSONObject dynamicProperties()
{
    coin++;
    TDJSONObject obj;
    obj.setNumber("coin",coin);
    return obj;
}
TDAnalytics::setDynamicSuperProperties(dynamicProperties);

2.6 イベントの所要時間の記録

あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。

//以下の例では、ユーザーがある商品ページに滞在した時間を集計します
//ユーザーが商品ページに入ったら計測を開始
TDAnalytics::timeEvent("stay_shop");
// do some thing...
//ユーザーが商品ページを離れたら計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが含まれます
TDAnalytics::track("stay_shop");

3. ユーザープロパティ

AEプラットフォームが対応しているユーザープロパティ設定APIは、userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppendです。

3.1 userSet

一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、元のプロパティ値を上書きします。そのユーザープロパティが存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします：

//この時点でusernameはTA
TDJSONObject properties;
properties.setString("username", "TA");
TDAnalytics::userSet(properties);
//この時点でusernameはAE
TDJSONObject newProperties;
newProperties.setString("username", "AE");
TDAnalytics::userSet(newProperties);

3.2 userSetOnce

送信するユーザープロパティを一度だけ設定すればよい場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。ここでは、初回課金時間の設定を例にします：

//first_payment_timeは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は引き続き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を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。ここでは、累積課金額を例にします：

//この時点でtotal_revenueは30
TDJSONObject userProperties;
userProperties.setNumber("total_revenue",30);
TDAnalytics::userAdd(userProperties);

//この時点でtotal_revenueは678
TDJSONObject newUserProperties;
newUserProperties.setNumber("total_revenue",648);
TDAnalytics::userAdd(newUserProperties);

設定するプロパティのkeyは文字列で、Valueには数値のみ指定できます。

3.4 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 userUniqAppend

userUniqAppendを呼び出して、配列型のユーザープロパティに要素を追加できます。userUniqAppendインターフェースを呼び出すと、追加するユーザープロパティの重複が排除されます。userAppendインターフェースでは重複は排除されないため、ユーザープロパティに重複が存在する場合があります。

//この時点でuser_listのプロパティ値は["apple","ball"]
TDJSONObject properties;
vector<string> dataArray;
dataArray.push_back("apple");
dataArray.push_back("ball");
properties.setList("user_list",dataArray);
TDAnalytics::userAppend(properties);

//この時点でuser_listのプロパティ値は["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);

//この時点でuser_listのプロパティ値は["apple","ball","cube"]
TDAnalytics::userUniqAppend(properties1);

4. その他の機能

4.1 デバイスIDの取得

SDKは初期化が完了すると、デバイスIDを自動的に生成してローカルキャッシュに記録します。同じアプリ/ゲームであれば、1台のデバイスのデバイスIDは変わりません。getDeviceId()を呼び出してデバイスIDを取得できます：

TDAnalytics::getDeviceId();

// デバイスIDをゲストIDとして使用
// TDAnalytics::setDistinctId(TDAnalytics::getDeviceId());

4.2 時間の補正

SDKはデフォルトで端末のローカル時間をイベント発生時間として送信します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、その場合は時間の補正を行うことで、イベント発生時間の正確性を確保できます。タイムスタンプ、NTPの2種類の時間補正方法を提供しています。

• サーバーから取得した現在のタイムスタンプを使用して、SDKの時間を補正できます。以降、時間を指定していないすべての呼び出し（イベントデータやユーザープロパティの設定操作を含む）では、補正後の時間が発生時間として使用されます。

// 1585633785954は現在のunixタイムスタンプ（単位はミリ秒）で、北京時間の2020-03-31 13:49:45に相当します
TDAnalytics::calibrateTime(1585633785954);

• NTPサーバーのアドレスを設定することもできます。設定後、SDKは渡されたNTPサービスのアドレスから現在時刻を取得し、SDKの時間を補正しようとします。デフォルトのタイムアウト時間（3秒）以内に正しい結果が返されなかった場合、以降はローカル時間でデータを送信します。

// Apple社のNTPサービスを使用して時間を補正
TDAnalytics::calibrateTimeWithNtp("time.apple.com");

1. NTPサービスによる時間補正には一定の不確実性があるため、タイムスタンプによる補正方法を優先的に検討することを推奨します

2. ネットワーク状況が良好な場合にユーザーのデバイスがすばやくサーバー時間を取得できるよう、NTPサーバーのアドレスは慎重に選択してください

4.3 データの即時送信

業務シナリオによっては、データをすぐにAEサーバーに送信したい場合があります。その場合はflushインターフェースを呼び出します

TDAnalytics::flush();

4.4 データの暗号化

v1.3.2以降、SDKは暗号化機能に対応しています。クライアントはAES+RSAでデータを暗号化し、サーバー側でデータを復号します。暗号化・復号機能はクライアントとサーバーの連携が必要です。詳しくはカスタマーサクセス担当者にお問い合わせください。

setEnableEncryptを呼び出して暗号化を有効にし、setSecretKeyでRSAの公開鍵情報を設定します

TDConfig config1(APPID,SERVER_URL);
config1.setEnableEncrypt(true);// 暗号化
config1.setSecretKey(TDSecretKey(_version, _secretKey));
TDAnalytics::init(config1);