応用ガイド

最終更新 2026/10/03

1. イベントの送信

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

1.1 通常イベント

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

// イベントプロパティを設定
TDProperties *properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("product_name", "goods_name", strlen("goods_name"), properties));
// カスタムプロパティ付きのイベントデータを送信。同様に、account_idとdistinct_idの少なくとも一方を設定する必要があります
TD_ASSERT(TD_OK == td_track("account_id", "distinct_id", "product_buy", properties, ta));
td_free_properties(properties);

1.2 初回イベント

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

TD_ASSERT(TD_OK == td_track_first_event("account_id", "distinct_id", "device_activation", "first_id", properties, ta));

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

1.3 更新可能イベント

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

// 更新可能イベントを送信。イベント名はUPDATABLE_EVENT、イベントIDはevent_id
// 送信後、イベントプロパティstatusは3、priceは100になります
TDProperties *properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("price",100,properties));
TD_ASSERT(TD_OK == td_add_int("status",3,properties));
TD_ASSERT(TD_OK == td_track_update("account_id", "distinct_id", "UPDATABLE_EVENT", "event_id",properties, ta));
td_free_properties(properties);
// 送信後、同じイベントプロパティstatusは5に更新され、priceは変わりません
TDProperties *new_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("status",5,new_properties));
TD_ASSERT(TD_OK == td_track_update("account_id", "distinct_id", "UPDATABLE_EVENT", "event_id",new_properties, ta));
td_free_properties(new_properties);

1.4 上書き可能イベント

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

// 上書き可能イベントを送信。イベント名はOVERWRITE_EVENT、イベントIDはevent_id
// 送信後、イベントプロパティstatusは3、priceは100になります
TDProperties *properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("price",100,properties));
TD_ASSERT(TD_OK == td_add_int("status",3,properties));
TD_ASSERT(TD_OK == td_track_overwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "event_id",properties, ta));
td_free_properties(properties);
// 送信後、同じイベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDProperties *new_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("status",5,new_properties));
TD_ASSERT(TD_OK == td_track_overwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "event_id",new_properties, ta));
td_free_properties(new_properties);

2. ユーザープロパティ

AEプラットフォームが対応しているユーザープロパティ設定APIは、td_user_set、td_user_setOnce、td_user_add、td_user_unset、td_user_delete、td_user_append、td_user_uniq_appendです。

2.1 td_user_set

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

//この時点でuser_nameはTA
TDProperties *user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("user_name", "TA", strlen("TA"), user_properties));
TD_ASSERT(TD_OK == td_user_set("account_id", "distinct_id", user_properties,ta));
td_free_properties(user_properties);

//この時点でuser_nameはAE
TDProperties *user_properties2 = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("user_name", "AE", strlen("AE"), user_properties2));
TD_ASSERT(TD_OK == td_user_set("account_id", "distinct_id", user_properties2,ta));
td_free_properties(user_properties2);

2.2 td_user_setOnce

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

//first_payment_timeは2018-01-01 01:23:45.678
TDProperties *user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("first_payment_time", "2018-01-01 01:23:45.678", strlen("2018-01-01 01:23:45.678"), user_properties));
TD_ASSERT(TD_OK == td_user_setOnce("account_id", "distinct_id", user_properties,ta));
td_free_properties(user_properties);

//first_payment_timeは引き続き2018-01-01 01:23:45.678
TDProperties *user_properties2 = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("first_payment_time", "2018-12-31 01:23:45.678", strlen("2018-12-31 01:23:45.678"), user_properties2));
TD_ASSERT(TD_OK == td_user_setOnce("account_id", "distinct_id", user_properties2,ta));
td_free_properties(user_properties2);

2.3 td_user_add

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

// ユーザープロパティを送信。この時点で"total_revenue"の値は30
TDProperties *user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("total_revenue", 30, user_properties));
TD_ASSERT(TD_OK == td_user_add("account_id", "distinct_id", user_properties, ta));
td_free_properties(user_properties);

// ユーザープロパティを送信。この時点で"total_revenue"の値は678
TDProperties *new_user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("total_revenue",648 , new_user_properties));
TD_ASSERT(TD_OK == td_user_add("account_id", "distinct_id", new_user_properties, ta));
td_free_properties(new_user_properties);

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

2.4 td_user_append

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

// この時点でuser_listのプロパティ値は["apple","ball"]
TDProperties *array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "ball", strlen("ball"), array_properties));
TD_ASSERT(TD_OK == td_user_append("account_id", "distinct_id", array_properties, ta));
td_free_properties(array_properties);

// この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
TDProperties *new_array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), new_array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "cube", strlen("cube"), new_array_properties));
TD_ASSERT(TD_OK == td_user_append("account_id", "distinct_id", new_array_properties, ta));
td_free_properties(new_array_properties);

2.5 td_user_uniq_append

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

// この時点でuser_listのプロパティ値は["apple","ball"]
TDProperties *array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "ball", strlen("ball"), array_properties));
TD_ASSERT(TD_OK == td_user_append("account_id", "distinct_id", array_properties, ta));
td_free_properties(array_properties);

// この時点でuser_listのプロパティ値は["apple","ball","cube"]
TDProperties *new_array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), new_array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "cube", strlen("cube"), new_array_properties));
TD_ASSERT(TD_OK == td_user_uniq_append("account_id","distinct_id", new_array_properties, ta));
td_free_properties(new_array_properties);

2.6 td_user_unset

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

TD_ASSERT(TD_OK == td_user_unset("account_id", "distinct_id", "test", ta));

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

2.7 td_user_delete

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

TD_ASSERT(TD_OK == td_user_delete("account_id", "distinct_id", ta));

3. その他の機能

3.1 BatchConsumer

注意

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

データをバッチでリアルタイムにAEサーバーへ送信します。転送ツールと組み合わせる必要はありません。キャッシュのサイズを設定でき、デフォルトは20です。つまり、キャッシュに保持されるデータの総数は最大20件です（20は1回あたりに送信するbatchの値で、設定可能です）。

// まず：CMakeLists.txtファイルを変更し、TDBatchConsumerタイプのライブラリファイルをビルドします

struct TDAnalytics* ta = NULL;
struct TDConsumer* consumer = NULL;

//configを生成
TDConfig *config = td_init_config();
// appidとurlを設定
char* appid = "APPID";
char* serverURL = "SERVER_URL";
TD_ASSERT(TD_OK == td_add_string("push_url", serverURL, strlen(serverURL), config));
TD_ASSERT(TD_OK == td_add_string("appid", appid, strlen(appid), config));

// SDKインスタンスを生成
if (TD_OK != td_init_consumer(&consumer, config)) {
    fprintf(stderr, "Failed to initialize the consumer.");
    return 1;
}
td_free_properties(config);
if (TD_OK != td_init(consumer, &ta)) {
    fprintf(stderr, "Failed to initialize the SDK.");
    return 1;
}

パラメータの説明:

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

• SERVER_URL: データの送信先URL

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