# C SDK 使用指南

提示

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

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

最新版本为：1.3.4

更新时间为：2022-03-03

C SDK 下载地址 (opens new window)

# 一、集成并初始化 SDK

# 1.1 集成 SDK

下载C SDK (opens new window)，进行解压后可将以下文件引入项目中

./c-sdk_version/include/thinkingdata.h
./c-sdk_version/lib/libthinkingdata.a

# 1.2 初始化 SDK

您可以通过以下方法获得 SDK 实例：

    //生成config
    TAConfig* config = ta_init_properties();

    //配置日志路径 YOUR_LOG_PATH 需要更改为日志存储的目录
    TA_ASSERT(TA_OK == ta_add_string("file_path", "YOUR_LOG_PATH", strlen("YOUR_LOG_PATH"), config));
    //配置日志前缀
    TA_ASSERT(TA_OK == ta_add_string("file_prefix", "test", strlen("test"), config));

    //按时间切分 默认按小时切分
    //TA_ASSERT(TA_OK == ta_add_int("rotate_mode", DAILY, config)); //按天切分
    TA_ASSERT(TA_OK == ta_add_int("rotate_mode", HOURLY, config)); //按小时切分

    //按文件大小切分，单位是MB
    //TA_ASSERT(TA_OK == ta_add_int("file_size", 1024, config));

    //生成SDK实例
    TALoggingConsumer* consumer = NULL;
    if (TA_OK != ta_init_logging_consumer(&consumer, config)) {
        fprintf(stderr, "Failed to initialize the consumer.");
        return 1;
    }
    ta_free_properties(config);

    ThinkingdataAnalytics *ta = NULL;
    if (TA_OK != ta_init(consumer, &ta)) {
        fprintf(stderr, "Failed to initialize the SDK.");
        return 1;
    }

TALoggingConsumer将会批量实时地生成日志文件，文件默认以小时切分，需要搭配 LogBus 进行上传。

YOUR_LOG_PATH 需要更改为日志存储的目录，您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

# 二、上报数据

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

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

# 2.1 发送事件

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

    const char* distinct_id = "ABC123";
    const char* account_id = "TA_10001";

    //上报不带自定义属性的事件数据，注意account_id 和 distinct_id 必须至少设置其中一个
    TA_ASSERT(TA_OK == ta_track(NULL, distinct_id, "test", NULL, ta));

    // 生成自定义属性
    TAProperties* properties = ta_init_properties();

    // 设置事件发生的时间，如果不设置的话，则默认使用为当前时间，**注意** #time的类型必须是time_t
    TA_ASSERT(TA_OK == ta_add_date("#time", time(NULL), 0, properties));

    // 设置用户的ip地址，TA系统会根据IP地址解析用户的地理位置信息，如果不设置的话，则默认不上报
    TA_ASSERT(TA_OK == ta_add_string("#ip", "192.168.1.1", strlen("192.168.1.1"), properties));

    // 添加自定义属性
    TA_ASSERT(TA_OK == ta_add_string("product_name", "商品", strlen("商品"), properties));
    TA_ASSERT(TA_OK == ta_add_number("price", 30.989, properties));
    TA_ASSERT(TA_OK == ta_add_int("coin", -30, properties));
    TA_ASSERT(TA_OK == ta_add_string("order_id", "abc_123", strlen("abc_123"), properties));
    TA_ASSERT(TA_OK == ta_add_date("login_time", time(NULL), 0, properties));
    TA_ASSERT(TA_OK == ta_add_bool("is_firstBuy", true, properties));
    TA_ASSERT(TA_OK == ta_add_bool("is_test", false, properties));

    // 从 v1.1.0版本 开始，您可以调用 `ta_append_array` 对 array 类型的属性进行追加操作。
    TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name1", strlen("product_name1"), properties));
    TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name2", strlen("product_name2"), properties));

    //上报带有自定义属性的事件数据，同样account_id 和 distinct_id 必须至少设置其中一个
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test", properties, ta));
    ta_free_properties(properties);

事件的名称是string类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感。
事件的属性类型是TAProperties，可以通过ta_add_string添加字符串型属性，ta_add_number添加数值型属性，ta_add_int添加int属性，ta_add_bool添加bool值，ta_add_date添加date类型值，ta_append_array添加数组类型。
Key 的值为属性的名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感。
Value 为该属性的值，可以是int、number、string、bool、date以及数组类型

# 2.2 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用ta_set_super_properties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

您还可以通过ta_unset_super_properties清除一个已设置的公共属性，也可以通过ta_clear_super_properties清空所有已设置的公共属性。

    //公共属性操作
    TAProperties* super_properties = ta_init_properties();

    //添加公共属性super_property_key和super_property_key2
    TA_ASSERT(TA_OK == ta_add_string("super_property_key", "super_property_value", strlen("super_property_value"), super_properties));
    TA_ASSERT(TA_OK == ta_add_string("super_property_key2", "super_property_value2", strlen("super_property_value"), super_properties));

    //设置公共属性
    ta_set_super_properties(super_properties, ta);

    //上报数据，此时事件中将会带有公共属性
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super", NULL, ta));

    //清除公共属性super_property_key2
    ta_unset_super_properties("super_property_key2", ta);

    //上报数据，公共属性super_property_key2被清除，此时事件中只会带有公共属性super_property_value
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super2", NULL, ta));

    //清空所有公共属性
    ta_clear_super_properties(ta);

    //上报数据，所有公共属性被清除，此时事件中不带有任何公共属性
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super3", NULL, ta));
    ta_free_properties(super_properties);

# 2.3 设置动态公共事件属性

在 v1.1.0 版本中，新增了动态公共属性的特性，即公共属性可以上报时获取当时的值，使得诸如会员等级之类的可变公共属性可以被便捷地上报。通过 ta_set_dynamic_properties 设置动态公共属性类之后，SDK 将会在事件上报时自动获取 dynamic_properties_func 中的属性，并添加到触发的事件中。以下例子是每次上报时将时间加入到事件中，当事件触发时，就会将 dynamic_properties_func 的返回值加入到事件属性中。

TAProperties *dynamic_properties_func() {
    TAProperties *properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_date("dynamic", time(NULL), 0, properties));
    return properties;
}
 // 设置动态公共属性
ta_set_dynamic_properties(&dynamic_properties_func, ta);

# 三、用户属性

TA 平台目前支持的用户属性设置接口为ta_user_set、ta_user_setOnce、ta_user_add、ta_user_del、ta_user_append。

# 3.1 ta_user_set

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

    // 上传用户属性，"user_name"的值为"ABC"
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "ABC", strlen("ABC"), user_properties));
    TA_ASSERT(TA_OK == ta_user_set(account_id, distinct_id, user_properties,ta));
    ta_free_properties(user_properties);

    //上传用户属性，该用户的"user_name"被设置成"XYZ"
    TAProperties* user_properties2 = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "XYZ", strlen("XYZ"), user_properties2));
    TA_ASSERT(TA_OK == ta_user_set(account_id, distinct_id, user_properties2,ta));
    ta_free_properties(user_properties2);

ta_user_set设置的用户属性的属性类型是TAProperties，可以通过ta_add_string添加字符串型属性，ta_add_number添加数值型属性，ta_add_int添加int属性，ta_add_bool添加bool值，ta_add_date添加date类型值，ta_append_array添加数组类型。
Key 的值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感。
Value 为该属性的值，可以是int、number、string、bool、date以及数组类型

# 3.2 ta_user_setOnce

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

    // 上传用户属性，"user_name"的值为"ABC"
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "ABC", strlen("ABC"), user_properties));
    TA_ASSERT(TA_OK == ta_user_setOnce(account_id, distinct_id, user_properties,ta));
    ta_free_properties(user_properties);

    //上传用户属性，该用户的"user_name"已设置因此忽略该属性设置
    //该用户的"user_age"没有被设置，因此设置值为18
    TAProperties* user_properties2 = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "XYZ", strlen("XYZ"), user_properties2));
    TA_ASSERT(TA_OK == ta_add_int("Age", 18, user_properties2));
    TA_ASSERT(TA_OK == ta_user_setOnce(account_id, distinct_id, user_properties2,ta));
    ta_free_properties(user_properties2);

ta_user_setOnce设置的用户属性类型及限制条件与ta_user_set一致。

# 3.3 ta_user_add

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

    //设置用户属性
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_int("Level", 3, user_properties));

    //上传用户属性，给该用户的"Level"属性加上3
    TA_ASSERT(TA_OK == ta_user_add(account_id, distinct_id, user_properties, ta));
    ta_free_properties(user_properties);

ta_user_add接口属性值只允许传入 int、number 类型。

# 3.4 ta_user_del

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

    TA_ASSERT(TA_OK == ta_user_del(account_id, distinct_id, ta));

# 3.5 ta_user_append

从 v1.1.0 版本开始，您可以调用 ta_user_append 对 array 类型的用户属性进行追加操作。

TAProperties *array_properties = ta_init_properties();
TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name3", strlen("product_name3"), array_properties));
TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name4", strlen("product_name4"), array_properties));
TA_ASSERT(TA_OK == ta_user_append(account_id, distinct_id, array_properties, ta));
ta_free_properties(array_properties);

# 四、其他操作

# 4.1 立即提交数据

    ta_flush(ta);

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

# 4.2 关闭 sdk

    ta_free(ta);
    ta_consumer_free(consumer);

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

# 五、相关预置属性

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

以下预置属性，是 C 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 的版本

# ChangeLog

# 1.3.4 2022-03-03

支持复杂数据类型

# 1.3.3 2022-02-18

修复 snprintf 可能导致的重名问题

# 1.3.2 2021-11-23

优化 windows 平台里的 snprintf 方法

# 1.3.1 2021-11-10

malloc失败时不再直接exit

# 1.3.0 2021-10-13

增加支持batch consumer

# 1.2.3 2021-09-23

修复#first_check_id无法正常处理的问题

# 1.2.2 2021-07-01

适配windows环境

# 1.2.1 2021-06-09

不再使用stdbool库

# 1.2.0 2020-12-07

支持指定 log 前缀
增加自动创建目录

# 1.1.0 2020-02-12

支持 array 数据
新增 user_append 接口
支持动态公共属性设置
支持设置“#uuid”，配合后台使用

# 1.0.0 2019-09-29

debug consumer
logger consumer
support track/user_set/user_setOnce/user_add/user_del
support super properties

← Android SDK Weex 框架支持 C# SDK 使用指南 →