C++ SDK 使用指南

提示

在接入前, 请先阅读接入前准备。

您可以在 GitHub (opens new window) 获取 C++ SDK 源码 和 Demo。

最新版本为：1.0.0

更新时间为：2022-05-20

一、集成并初始化 SDK

集成 SDK

1. 将Demo中的thirdPark文件夹拖入工程引入；
2. CMakeLists.txt 中的具体参数，参考Demo中的CMakeLists.txt；

初始化

// 导入头文件(每个平台以及IDE的路径不一样，自行适合调整)
#include "thirdPark/tacpp/include/tacpp/ThinkingDataAnalyticsSDK.h"

(1)LoggerConsumer： 批量实时写本地文件，文件以天为分隔，需要搭配 LogBus 进行上传

string LOG_DIRECTORY = "../trackLog";
TaSDK::LoggerConsumer::Config config = TaSDK::LoggerConsumer::Config(LOG_DIRECTORY);

// 默认以天为分割，如果您想按小时切分文件
// config.rotateMode = TaSDK::LoggerConsumer::HOURLY;

TaSDK::LoggerConsumer logConsumer = TaSDK::LoggerConsumer(config);
TaSDK::ThinkingDataAnalytics tga = TaSDK::ThinkingDataAnalytics(logConsumer, true);

LOG_DIRECTORY为写入本地的文件夹地址，您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

(2)DebugConsumer： 逐条实时地向 TA 服务器传输数据，不需要搭配传输工具，如果数据出现错误，整条数据都将不会入库，并且返回详细的错误说明，不建议在正式环境中使用

TaSDK::DebugConsumer debugConsumer = TaSDK::DebugConsumer(SERVER_URI, APP_ID);
TaSDK::ThinkingDataAnalytics tga = TaSDK::ThinkingDataAnalytics(debugConsumer);

如果您不想数据入库，只想校验数据格式，您可以初始化代码如下：

TaSDK::DebugConsumer debugConsumer = TaSDK::DebugConsumer(SERVER_URI, APP_ID);
TaSDK::ThinkingDataAnalytics tga = TaSDK::ThinkingDataAnalytics(debugConsumer, false);

SERVER_URI为传输数据的 serverUrl，APP_ID为您的项目的 appId

如果您使用的是云服务，请输入以下 URL: https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL: http://数据采集地址

二、上报数据

在 SDK 初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TA 后台，我们推荐您先上传几个关键事件。

如果您对需要发送什么样的事件有疑惑，可以查看快速使用指南了解更多信息。

2.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以用户付费作为范例：

TaSDK::PropertiesNode 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 = "测试字符串1";
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事件
tga.track(accountId, distincId, eventName, event_properties);

• 事件的名称是 string 类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感。
• 自定义属性的 Key 的值为属性的名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感。
• 自定义属性的 Value 为该属性的值。

三、用户属性

3.1 user_set

对于一般的用户属性，您可以调用user_set来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致：

// user_set
TaSDK::PropertiesNode userSet_properties;
userSet_properties.SetString("userName", "test");
//上传用户属性
tga.user_set(accountId, distincId, userSet_properties);

属性格式要求与事件属性保持一致。

3.2 user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

// user_setOnce
TaSDK::PropertiesNode userSetOnce_properties;
userSetOnce_properties.SetString("user_one_name", "ABC");
//上传用户属性, 新建"user_one_name"，值为"ABC"
tga.user_setOnce(accountId, distincId, userSetOnce_properties);

属性格式要求与事件属性保持一致。

3.3 user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。

// user_add
TaSDK::PropertiesNode userAdd_properties;
userAdd_properties.SetNumber("cash", 66);
// 上传用户属性，此时"cash"的值为66
tga.user_add(accountId, distincId, userAdd_properties);

设置的属性key为字符串，Value 只允许为数值。

3.4 user_del

如果您要删除某个用户，可以调用user_del将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

// user_del
tga.user_del(accountId, distincId);

3.5 user_append

您可以调用 user_append 为 List 类型的用户属性追加元素:

// user_append
TaSDK::PropertiesNode userAppend_properties;
vector<string> userAppenListValue;
userAppenListValue.push_back("11");
userAppenListValue.push_back("33");
userAppend_properties.SetList("arr1", userAppenListValue);
// 为arr1的数组类型追加属性
tga.user_append(accountId, distincId, userAppend_properties);

属性格式要求与事件属性保持一致。

3.6 user_unset

当您需要清空某个用户的用户属性的值时，可以调用 user_unset 进行清空。

// user_unset
TaSDK::PropertiesNode userUnset_properties;
userUnset_properties.SetNumber("userName", 0);
// 清空该用户userName属性值
tga.user_unset(accountId, distincId, userUnset_properties);

user_unset: 的传入值为被清空属性的 Key 值。

3.7 user_uniq_append

您可以调用 user_uniqAppend 为 List 类型的用户属性进行去重追加元素:

// user_uniq_append
TaSDK::PropertiesNode userUniqAppend_properties;
vector<string> userUniqAppenListValue;
userUniqAppenListValue.push_back("55");
userUniqAppenListValue.push_back("22");
userUniqAppenListValue.push_back("33");
userUniqAppenListValue.push_back("66");
userUniqAppenListValue.push_back("55");
// 为arr1的数组类型去重追加属性
userUniqAppend_properties.SetList("arr1", userUniqAppenListValue);
tga.user_uniqAppend(accountId, distincId, userUniqAppend_properties);

四、其他操作

4.1 立即提交数据

tga.flush();

立即提交数据到相应的接收器

4.2 关闭 sdk

tga.close();

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

五、相关预置属性

5.1 所有事件带有的预置属性

以下预置属性，是 Erlang SDK 中所有事件（包括自动采集事件）都会带有的预置属性

属性名	中文名	说明
#ip	IP 地址	用户的 IP 地址，需要进行手动设置，TA 将以此获取用户的地理位置信息
#country	国家	用户所在国家，根据 IP 地址生成
#country_code	国家代码	用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province	省份	用户所在省份，根据 IP 地址生成
#city	城市	用户所在城市，根据 IP 地址生成
#lib	SDK 类型	您接入 SDK 的类型，如 tga_c_sdk 等
#lib_version	SDK 版本	您接入 C SDK 的版本

六、进阶功能

6.1 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

// 可更新事件
eventName = "update_event";
string updateEventId = "update_001";
TaSDK::PropertiesNode update_event_properties;
update_event_properties.SetString("price", "100");
update_event_properties.SetString("status", "3");
// 上报后事件属性 status 为 3, price 为 100
tga.track_update(accountId, distincId, eventName, updateEventId, update_event_properties);

TaSDK::PropertiesNode update_event_new_properties;
update_event_new_properties.SetString("status", "5");
// 上报事件后, 属性 status 被更新为 5, price 不变
tga.track_update(accountId, distincId, eventName, updateEventId, update_event_new_properties);

6.2 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

// 可重写事件
eventName = "overWrite_event";
string overWriteEventId = "overWrite_001";
TaSDK::PropertiesNode overWrite_event_properties;
overWrite_event_properties.SetString("money", "99");
overWrite_event_properties.SetString("code", "10");
// 上报后事件属性 code 为 10, money 为 99
tga.track_overwrite(accountId, distincId, eventName, overWriteEventId, overWrite_event_properties);

TaSDK::PropertiesNode overWrite_event_new_properties;
overWrite_event_new_properties.SetString("money", "66");
// 上报后事件属性 money 被更新为 66, code 属性被删除
tga.track_overwrite(accountId, distincId, eventName, overWriteEventId, overWrite_event_new_properties);

6.3 首次事件

使用“首次事件校验”特性，必须要在properties中设置#first_check_id字段，类型为字符串，该字段是校验首次事件的标识 ID，该 ID 首条出现的数据将入库，之后出现的都无法入库。不同事件的#first_check_id互相独立，因此每个事件的首次校验互不干扰

// 首次事件
eventName = "first_envet";
event_properties.SetString("#first_check_id", "first_event");
tga.track_first(accountId, distincId, eventName, event_properties);

ChangeLog

v1.0.0 2022/05/20

• 支持debug_consumer
• 支持log_consumer