跳到主要内容

进阶指南

最近更新 2026/10/03

一、发送事件​

在 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);

二、用户属性​

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.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://数据采集地址绑定域名
这篇文档对你有帮助吗？
本页内容