応用ガイド

最終更新 2026/10/03

1. イベントの送信

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

1.1 通常イベント

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

TDPropertiesNode event_properties;
event_properties.SetString("name1", "XZ_debug");
event_properties.SetString("name2", "logbugs");
event_properties.SetString("name3", "name3");
event_properties.SetString("#uuid", "1234567890");
event_properties.SetNumber("test_number_int", 3);
event_properties.SetNumber("test_number_double", 3.14);
event_properties.SetBool("test_bool", true);
std::string test_string = "test_string";
event_properties.SetString("test_stl_string1", test_string);
event_properties.SetDateTime("test_time1", time(nullptr), 0);
timeb t = {};
ftime(&t);
event_properties.SetDateTime("#time", t.time, t.millitm);
std::vector<std::string> test_list;
test_list.push_back("item11");
test_list.push_back("item21");
event_properties.SetList("test_list1", test_list);

// track event
te.track("accountId", "distinctId", "eventName", event_properties);

1.2 初回イベント

初回イベントとは、あるデバイスまたはその他のディメンションのIDに対して、一度だけ記録されるイベントです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。「初回イベントの検証」機能を使用するには、propertiesに#first_check_idフィールドを設定する必要があります。タイプは文字列です。

TDPropertiesNode event_properties;
// first event
event_properties.SetString("#first_check_id", "first_event");
te.track_first("accountId", "distinctId", "eventName", event_properties);

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

1.3 更新可能イベント

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

// updatable event
std::string updateEventId = "update_001";
TDPropertiesNode update_event_properties;
update_event_properties.SetString("price", "100");
update_event_properties.SetString("status", "3");
// the value of "status" is 3, the value of "price" is 100
te.track_update("accountId", "distinctId", "eventName", updateEventId, update_event_properties);

TDPropertiesNode update_event_new_properties;
update_event_new_properties.SetString("status", "5");
// the value of "status" become 5, the value of "price" is still 100
te.track_update("accountId", "distinctId", "eventName", updateEventId, update_event_new_properties);

1.4 上書き可能イベント

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

// overwrite event
std::string overWriteEventId = "overWrite_001";
TDPropertiesNode overWrite_event_properties;
overWrite_event_properties.SetString("money", "99");
overWrite_event_properties.SetString("code", "10");
// the value of "code" is 10, the value of "money" is 99
te.track_overwrite("accountId", "distinctId", "eventName", overWriteEventId, overWrite_event_properties);

TDPropertiesNode overWrite_event_new_properties;
overWrite_event_new_properties.SetString("money", "66");
// The "money" has changed to 66，The "code" will be deleted
te.track_overwrite("accountId", "distinctId", "eventName", overWriteEventId, overWrite_event_new_properties);

2. ユーザープロパティ

AEプラットフォームでは、次のユーザープロパティ設定APIに対応しています：user_set、user_setOnce、user_add、user_unset、user_del、user_append、user_uniqAppend。

2.1 user_set

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

TDPropertiesNode userSet_properties;
userSet_properties.SetString("userName", "A");
// set user properties. the value of "userName" is "A"
te.user_set("accountId", "distinctId", userSet_properties);

userSet_properties.SetString("userName", "B");
// set user properties again，the value of "userName" will change to "B"
te.user_set("accountId", "distinctId", userSet_properties);

2.2 user_setOnce

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

// user_setOnce
TDPropertiesNode userSetOnce_properties;
userSetOnce_properties.SetString("user_one_name", "A");
// create "user_one_name" property, and the value is "A"
te.user_setOnce("accountId", "distinctId", userSetOnce_properties);

userSetOnce_properties.SetString("user_one_name", "B");
// the value of "user_one_name" is still "A"
te.user_setOnce("accountId", "distinctId", userSetOnce_properties);

2.3 user_add

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

// user_add
TDPropertiesNode userAdd_properties;
userAdd_properties.SetNumber("cash", 30);
// the value of "cash" is 30
te.user_add("accountId", "distinctId", userAdd_properties);

userAdd_properties.SetNumber("cash", 60);
// set user properties again，the value of "cash" is 90 now
te.user_add("accountId", "distinctId", userAdd_properties);

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

2.4 user_append

user_appendを呼び出して、配列型のユーザープロパティに要素を追加できます。

// user_append
TDPropertiesNode userAppend_properties;
std::vector<std::string> userAppendListValue;
userAppendListValue.push_back("11");
userAppendListValue.push_back("33");
userAppend_properties.SetList("arr1", userAppendListValue);
// the value of "arr1" is ["11", "33"]
te.user_append("accountId", "distinctId", userAppend_properties);

TDPropertiesNode userAppend_properties_new;
std::vector<std::string> userAppendListValueNew;
userAppendListValueNew.push_back("22");
userAppendListValueNew.push_back("33");
userAppend_properties_new.SetList("arr1", userAppendListValueNew);
// the value of "arr1" is ["11", "33", "22", "33"]
te.user_append("accountId", "distinctId", userAppend_properties_new);

2.5 user_uniqAppend

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

// user_uniqAppend
TDPropertiesNode userAppend_properties;
std::vector<std::string> userAppendListValue;
userAppendListValue.push_back("11");
userAppendListValue.push_back("33");
userAppend_properties.SetList("arr1", userAppendListValue);
// the value of "arr1" is ["11", "33"]
te.user_uniqAppend("accountId", "distinctId", userAppend_properties);

TDPropertiesNode userAppend_properties_new;
std::vector<std::string> userAppendListValueNew;
userAppendListValueNew.push_back("22");
userAppendListValueNew.push_back("33");
userAppend_properties_new.SetList("arr1", userAppendListValueNew);
// the value of "arr1" is ["11", "33", "22"]
te.user_uniqAppend("accountId", "distinctId", userAppend_properties_new);

2.6 user_unset

ユーザーのユーザープロパティ値をクリアする場合は、user_unsetを呼び出して指定したプロパティをクリアできます。そのプロパティがまだクラスターで作成されていない場合、user_unsetはそのプロパティを作成しません

// user_unset
TDPropertiesNode userUnset_properties;
userUnset_properties.SetNumber("userName", 0);
// the value of "userName" will be reset after executed "user_unset"
te.user_unset("accountId", "distinctId", userUnset_properties);

user_unset: には、クリアするプロパティのKey値を渡します。

2.7 user_del

あるユーザーを削除する場合は、user_delを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。この操作は元に戻せない結果をもたらす可能性があるため、慎重に使用してください。

te.user_del("accountId", "distinctId");

3. その他の機能

3.1 BatchConsumer

注意

データ量が多すぎる場合やネットワークに異常がある場合は、データが失われるおそれがあるため、本番環境での使用はお勧めしません

データをバッチでリアルタイムにAEサーバーへ送信します。転送ツールと組み合わせる必要はありません。

TDBatchConsumer batchConsumer("APPID","SERVER_URL", 10);
TDAnalytics te(batchConsumer, true);

パラメータの説明:

• APPID: プロジェクトのAPPIDです。AE管理画面の「プロジェクト管理」ページで取得できます

• SERVER_URL: データの送信先URL

  • クラウドサービスをご利用の場合は、次を入力します: https://global-receiver-ta.thinkingdata.cn
  • プライベートデプロイ版をご利用の場合は、データ収集アドレスにドメインをバインドし、HTTPS証明書を設定してください：https://データ収集アドレスにバインドしたドメイン