# C SDK 使用指南

提示

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

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

最新版本为:1.2.2

更新时间为:2021-07-01

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.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