応用ガイド

最終更新 2026/10/07

1. ユーザーIDの設定

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

1.1 ゲストIDの設定

ヒント

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

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

Appで独自のゲストID管理体系を持っている場合は、Identifyを呼び出してゲストIDを設定できます：

// ゲストIDをThinkerに設定
ThinkingAnalyticsAPI::Identify("Thinker");

現在のゲストIDを取得する場合は、DistinctID()を呼び出します：

//ゲストIDを返す
ThinkingAnalyticsAPI::DistinctID().c_str()

1.2 アカウントIDの設定

ユーザーがログインする際にLoginを呼び出してユーザーのアカウントIDを設定できます。AEプラットフォームはアカウントIDを識別IDとして使用し、設定したアカウントIDはLogOutを呼び出すまで保持されます。Loginを複数回呼び出すと、以前のアカウントIDが上書きされます

// ユーザーのログイン固有識別子。このデータは送信データの#account_idに対応し、この時点で#account_idの値はTA
ThinkingAnalyticsAPI::Login("TA");

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

1.3 アカウントIDのクリア

ユーザーがログアウトした後、LogOutを呼び出してアカウントIDをクリアできます。次にLoginを呼び出すまでは、ゲストIDが識別IDとして使用されます。

ThinkingAnalyticsAPI::LogOut();

LogOutは、明示的なログアウトイベントが発生したとき（たとえばユーザーがアカウントを解約したとき）にのみ呼び出すことをお勧めします。Appを閉じるときに呼び出す必要はありません。

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

2. イベントの送信

SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。

2.1 通常イベント

Trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する場合を例にします：

//ストア購入イベント
TDJSONObject event_properties;
event_properties.SetString("product_name", "商品名");
ThinkingAnalyticsAPI::Track("product_buy", event_properties);

2.2 初回イベント

初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。

TDJSONObject jsonObject1;
jsonObject1.SetString("test","test");
TDFirstEvent *firstEvent = new TDFirstEvent("device_activation",jsonObject1);
ThinkingAnalyticsAPI::Track(firstEvent);
delete firstEvent;

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

//ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集
TDJSONObject jsonObject1;
jsonObject1.SetString("test","test");
TDFirstEvent *firstEvent = new TDFirstEvent("account_activation",jsonObject1);
firstEvent->setFirstCheckId("TA");
ThinkingAnalyticsAPI::Track(firstEvent);
delete firstEvent;

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

2.3 更新可能イベント

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

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

// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDJSONObject jsonObject1;
jsonObject1.SetNumber("status", 5);
TDUpdatableEvent *updatableEvent1 = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject1,"test_event_id");
ThinkingAnalyticsAPI::Track(updatableEvent1);
delete updatableEvent1;

2.4 上書き可能イベント

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

// 例：上書き可能なイベントを送信。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDJSONObject jsonObject;
jsonObject.SetNumber("status", 3);
jsonObject.SetNumber("price", 100);
TDOverWritableEvent *event = new TDOverWritableEvent("OVERWRITE_EVENT",jsonObject,"test_event_id");
ThinkingAnalyticsAPI::Track(event);
delete event;

// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDJSONObject jsonObject1;
jsonObject1.SetNumber("status", 5);
TDOverWritableEvent *event1 = new TDOverWritableEvent("OVERWRITE_EVENT",jsonObject1,"test_event_id");
ThinkingAnalyticsAPI::Track(event1);
delete event1;

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

共通イベントプロパティとは、すべてのイベントで送信されるプロパティのことです。

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

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

TDJSONObject superProperties;
superProperties.SetNumber("vip_level",2);
ThinkingAnalyticsAPI::SetSuperProperty(superProperties);

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

//特定の共通イベントプロパティをクリア
ThinkingAnalyticsAPI::UnsetSuperProperties("Channel");
//すべての共通イベントプロパティをクリア
ThinkingAnalyticsAPI::ClearSuperProperty();
//すべての共通イベントプロパティを取得
TDJSONObject superJson;
ThinkingAnalyticsAPI::GetSuperProperties(superJson);

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

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

TDJSONObject GetDynamicSuperProperties(){
    TDJSONObject json;
    json.SetNumber("coin",10);
    return json;
}
ThinkingAnalyticsAPI::Init(config);
ThinkingAnalyticsAPI::SetDynamicSuperProperties(GetDynamicSuperProperties);

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

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

//以下の例では、ユーザーが特定の商品ページに滞在した時間を集計します
//ユーザーが商品ページに入り、計測を開始
ThinkingAnalyticsAPI::TimeEvent("stay_shop");
/**do something
.......
**/
//ユーザーが商品ページを離れ、計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが付与されます
TDJSONObject event_properties;
ThinkingAnalyticsAPI::Track("stay_shop", event_properties);

3. ユーザープロパティ

AEプラットフォームが現在対応しているユーザープロパティ設定APIは、UserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppend、UserUniqAppendです。

3.1 UserSet

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

TDJSONObject userProperties;
userProperties.SetString("username", "TA");
ThinkingAnalyticsAPI::UserSet(userProperties);
//この時点でusernameはAE
TDJSONObject userProperties1;
userProperties1.SetString("username", "AE");
ThinkingAnalyticsAPI::UserSet(userProperties1);

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");
ThinkingAnalyticsAPI::UserSetOnce(userProperties);

//first_payment_timeは引き続き2018-01-01 01:23:45.678
TDJSONObject userProperties1;
userProperties1.SetString("first_payment_time","2018-12-31 01:23:45.678");
ThinkingAnalyticsAPI::UserSetOnce(userProperties1);

3.3 UserAdd

数値型のプロパティを送信する場合は、UserAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。ここでは、累積課金額を例にします：

//この時点でtotal_revenueは30
TDJSONObject userProperties;
userProperties.SetNumber("total_revenue",30);
ThinkingAnalyticsAPI::UserAdd(userProperties);
//この時点でtotal_revenueは678
TDJSONObject userProperties1;
userProperties1.SetNumber("total_revenue",648);
ThinkingAnalyticsAPI::UserAdd(userProperties1);

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

3.4 UserUnset

ユーザーの特定のプロパティをリセットする場合は、UserUnsetを呼び出して、そのユーザーの指定したユーザープロパティの値をクリアできます。このインターフェースには、文字列またはリスト型のパラメータを渡せます：

ThinkingAnalyticsAPI::UserUnset("userUnset_key");

渡す値は、クリアするプロパティのKey値です。

3.5 UserDelete

あるユーザーを削除する場合は、UserDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。

ThinkingAnalyticsAPI::UserDelete();

3.6 UserAppend

UserAppendを呼び出して、List型のユーザープロパティに要素を追加できます：

TDJSONObject userProperties;
vector<string> listValue;
listValue.push_back("apple");
listValue.push_back("ball");
userProperties.SetList("user_list",listValue);
ThinkingAnalyticsAPI::UserAppend(userProperties);

3.7 UserUniqAppend

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

//この時点でuser_listのプロパティ値は["apple","ball"]
TDJSONObject userProperties1;
vector<string> listValue1;
listValue1.push_back("apple");
listValue1.push_back("ball");
userProperties1.SetList("user_list",listValue1);
ThinkingAnalyticsAPI::UserAppend(userProperties1);

//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
TDJSONObject userProperties2;
vector<string> listValue2;
listValue2.push_back("apple");
listValue2.push_back("cube");
userProperties2.SetList("user_list",listValue2);
ThinkingAnalyticsAPI::UserAppend(userProperties2);

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

4. 暗号化機能

v1.3.7以降、SDKはAES+RSAによるデータの暗号化に対応しています。データ暗号化機能はクライアントとサーバーの連携が必要です。具体的な使用方法については、カスタマーサクセス担当者にお問い合わせください。

TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.EnableEncrypt(1,"publickKey");
ThinkingAnalyticsAPI::Init(config);

5. その他の機能

5.1 SDKログの出力

EnableLogインターフェースでSDKログのスイッチをオンにできます。オンにすると、送信したデータがIDEのコンソールに出力されます。

ThinkingAnalyticsAPI::EnableLog(true);

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はデフォルトで端末のローカル時間をイベント発生時間として使用します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、時間の校正によってイベント発生時間の正確さを確保できます。タイムスタンプ、自動の2種類の時間校正方法を提供しています。

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

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

• 自動時間校正を設定することもできます。設定すると、SDKはconfigインターフェースから現在時刻の取得を試み、SDKの時間を校正します。正しい結果が返されなかった場合は、以降はローカル時間でデータを送信します。

TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.enableAutoCalibrated = true;
ThinkingAnalyticsAPI::Init(config);

5.4 データの即時送信

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

ThinkingAnalyticsAPI::Flush();

5.5 デバイスIDの取得

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

ThinkingAnalyticsAPI::GetDeviceId();

5.6 デフォルトタイムゾーンの設定

デフォルトでは、SDKはインターフェースを呼び出した時点の端末のローカル時間をイベント発生時間として送信します。デフォルトタイムゾーンを設定するインターフェースで既定のタイムゾーンを指定することもできます。これにより、すべてのイベントのイベント時間が設定したタイムゾーンに合わせられます：

TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.zoneOffset = 5;
ThinkingAnalyticsAPI::Init(config);

注意：指定したタイムゾーンでイベント時間を合わせると、デバイスのローカルタイムゾーンの情報は失われます。デバイスのローカルタイムゾーンの情報を保持する必要がある場合は、現時点ではイベントに関連プロパティを自分で追加する必要があります。