C SDK 使用说明

最后更新于:2019-03-27 11:10:05

在使用前,请先阅读数据模型的介绍。

1. 集成神策分析 SDK

开发者可以在 C 程序中集成 神策分析 SDK,使用神策分析采集并分析用户数据。

从 Github 下载 神策分析 SDK 的源代码,可在本地编译,通过静态库的形式加入项目中,也可以直接将源文件引入项目中。SDK 源代码包括:

  ./LICENSE
  ./Makefile                // Makefile
  ./sensors_analytics.h     // SDK 头文件
  ./sensors_analytics.c     // SDK 源文件
  ./demo.c                  // Demo 程序,使用 LoggingConsumer 将日志文件输出到本地磁盘

开发者编译 SDK 后,会生成静态库:

  ./output/include/sensors_analytics.h
  ./output/lib/libsensorsanalytics.a

SDK 符合 ANSI C99 规范,部分功能依赖 POSIX 库,不依赖第三方库。

开发者通过 C SDK 在程序中记录用户行为数据。SDK 将格式化的行为数据以日志文件的形式输出到本地磁盘文件中,开发者需要通过神策分析的 LogAgent 工具 将日志文件传输到神策分析中。LogAgent 工具 保证日志传输的时效性和完整性。

2. 初始化神策分析 SDK

在程序中使用

// 初始化神策分析对象
//
//  @param consumer<in>         日志数据的“消费”方式
//  @param sa<out>              初始化的神策分析实例
//
// @return SA_OK 初始化成功,否则初始化失败
int sa_init(struct SAConsumer* consumer, struct SensorsAnalytics** sa);

初始化神策分析实例,通过它实现 SDK 各项功能。其中第一个参数 consumer 对象负责“消费”用户行为日志,在程序中使用

// 初始化 Logging Consumer
//
//  @param file_name<in>    日志文件名,例如: /data/logs/http.log
//  @param consumer<out>    SALoggingConsumer 实例
//
// @return SA_OK 初始化成功,否则初始化失败
int sa_init_logging_consumer(const char* file_name, SALoggingConsumer** consumer);

初始化 SALoggingConsumer 实例,它负责将用户行为日志输出到本地磁盘。

    // 初始化 SALogingConsumer 实例
    SALoggingConsumer* consumer = NULL;
    if (SA_OK != sa_init_logging_consumer("./demo.out", &consumer)) {
        fprintf(stderr, "Failed to initialize the consumer.");
        return 1;
    }

    SensorsAnalytics *sa = NULL;
    if (SA_OK != sa_init(consumer, &sa)) {
        fprintf(stderr, "Failed to initialize the SDK.");
        return 1;
    }

    // ... 使用神策分析进行各种操作

    // 将本地缓存的数据同步到文件或 Sensors Analtycis 中
    sa_flush(sa);
    // 释放 Sensors Analtycis 实例
    sa_free(sa);

3. 追踪事件

首次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

  • 图片社交产品,可以追踪用户浏览图片和评论事件
  • 电商产品,可以追踪用户注册、浏览商品和下订单等事件

用户通过

// 跟踪一个用户的行为
//
//  @param distinct_id<in>      用户ID
//  @param event<in>            事件名称
//  @param properties<in>       事件属性,SAProperties 对象,NULL表示无事件属性
//  @param sa<in/out>           SensorsAnalytics 实例
//
// @return SA_OK 追踪成功,否则追踪失败
#define sa_track(distinct_id, event, properties, sa)

接口记录事件。开发者必须传入用户 ID(distinct_id)和事件名(event)两个参数,标记用户和事件名称,同时,开发者可以在第三个参数传入一个 SAProperties 对象,为事件添加自定义事件属性,传入 NULL 表示无自定义事件属性,在自定义属性中需要包含 $is_login_id 属性来说明 distinct_id 是否为登录 ID。以电商产品为例,可以这样追踪一次购物行为:

    // 记录用户提交订单事件

    // 初始化事件属性
    properties = sa_init_properties();
    if (NULL == properties) {
        fprintf(stderr, "Failed to initialize the properties.");
        return 1;
    }

    // 添加操作系统属性,通过请求中的UA,可以解析出用户使用设备的操作系统是 iOS
    assert(SA_OK == sa_add_string("$os", "iOS", strlen("iOS"), properties));
    // 添加操作系统版本属性
    assert(SA_OK == sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties));
    // 添加 IP 地址属性,$ip 是预置属性,神策分析会自动根据这个解析省份、城市
    assert(SA_OK == sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties));
    // 添加商品名称属性
    assert(SA_OK == sa_add_string("product_name", "XX手机", 8, properties));
    // 添加商品价格属性
    assert(SA_OK == sa_add_number("product_price", 5888, properties));
    //  $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 SA_TRUE,否则为 SA_FALSE,默认为 SA_FALSE
    assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);
    // 记录购买商品事件
    assert(SA_OK == sa_track(cookie_id, "SubmitOrder", properties, sa));

    // 释放事件属性实例
    sa_free_properties(properties);

3.1 事件属性

如前文中的样例,开发者追踪的事件可以自定义事件的属性,例如购买商品事件中,将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中,事件属性可以作为统计过滤条件使用,也可以作为维度进行多维分析。对于事件属性,神策分析有一些约束:

  • 事件属性是一个 SAProperties 对象,SDK 提供接口由开发者进行初始化和释放;
  • SAProperties 中每个元素描述一个事件属性,属性名称必需是字符串类型,以大小写字母开头,由字母和数字组成,长度不超过100个字符;
  • SAProperties 中元素的值为事件属性值,支持 StringNumberBoolListDate,对于神策分析中事件属性的更多约束,请参考 数据格式

开发者可以通过以下接口,向 SAProperties 对象加入属性值,如加入 Bool 类型的属性:

// 向事件属性或用户属性添加 Bool 类型的属性
//
// @param key<in>           属性名称
// @param bool_<in>         SABool 对象,属性值
// @param properties<out>   SAProperties 对象
//
// @return SA_OK 添加成功,否则失败
int sa_add_bool(const char* key, SABool bool_, SAProperties* properties);

其中属性名称必须为大小写字母开头、长度不超过100的由字母和数字组成的字符串。加入 Number 类型的属性:

// 向事件属性或用户属性添加 Number 类型的属性
//
// @param key<in>           属性名称
// @param number_<in>       属性值
// @param properties<out>   SAProperties 对象
//
// @return SA_OK 添加成功,否则失败
int sa_add_number(const char* key, double number_, SAProperties* properties);

加入 Date 类型的属性,其中第一个参数为单位为秒的时间戳,如系统函数 time(NULL) 的返回值,第二个参数为毫秒部分:

// 向事件属性或用户属性添加 Date 类型的属性
//
// @param key<in>           属性名称
// @param seconds<in>       时间戳,单位为秒
// @param microseconds<in>  时间戳中毫秒部分
// @param properties<out>   SAProperties 对象
//
// @return SA_OK 添加成功,否则失败
int sa_add_date(const char* key, time_t seconds, int microseconds, SAProperties* properties);

加入 String 类型的属性,字符串必须为 UTF-8 编码,字符串长度为实际的 UTF-8 长度,如一个汉字占 3 个字节:

// 向事件属性或用户属性添加 String 类型的属性
//
// @param key<in>           属性名称
// @param string_<in>       字符串的句柄
// @param length<in>        字符串长度
// @param properties<out>   SAProperties 对象
//
// @return SA_OK 添加成功,否则失败

向 List 类型的属性中添加 String 对象:

// 向事件属性或用户属性的 List 类型的属性中插入新对象,对象必须是 String 类型的
//
// @param key<in>           属性名称
// @param string_<in>       字符串的句柄
// @param length<in>        字符串长度
// @param properties<out>   SAProperties 对象
//
// @return SA_OK 添加成功,否则失败
int sa_append_list(
        const char* key,
        const char* string_,
        unsigned int length,
        SAProperties* properties);

具体使用方式,可以参考上一节中的样例。

3.1.1 系统预置属性

如前文中样例,事件属性中以 '$' 开头的属性为系统预置属性,在自定义事件属性中填入对应 '$' 开头的属性值可以覆盖这些预置属性:

  • $ip - 通过 sa_add_string()SAProperties 对象加入该属性,神策分析会自动根据 IP 地址解析用户的省份、城市信息;
  • $time - 通过 sa_add_date()SAProperties 对象加入该属性,神策分析将事件时间设置为属性值的时间。请注意,神策分析默认会过滤忽略 2 年前或 1 小时后的数据,如需修改这个限制请联系我们的技术支持。

关于其他更多预置属性,请参考 数据格式 中 '预置属性' 一节。

4. 用户识别

在服务端应用中,神策分析也要求为每个事件设置用户的 Distinct Id,这有助于神策分析提供更准确的留存率等数据。

对于注册用户,推荐使用系统中的用户 ID 作为 Distinct Id,不建议使用用户名、Email、手机号码等可以被修改的信息。

4.1 用户注册/登录

当同一个用户的 Distinct Id 发生变化时(一般情况为匿名用户注册行为),可以通过

// 关联匿名用户和注册用户
//
// @param distinct_id<in>       用户的注册 ID
// @param origin_id<in>         被关联的用户匿名 ID
// @param properties<in>        事件属性
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 追踪关联事件成功,否则失败
#define sa_track_signup(distinct_id, origin_id, properties, sa)

将旧的 Distinct Id 和新的 Distinct Id 关联,以保证用户分析的准确性。例如:

    // 初始化神策分析 SDK ...

    // 用户未注册前的匿名 ID (匿名 ID 由前端传过来)   
    const char* anonymous_id = '9771C579-71F0-4650-8EE8-8999FA717761';
    # 未注册前的匿名用户浏览商品
    assert(SA_OK == sa_track(anonymous_id, "ViewProduct", NULL, sa));

    properties = sa_init_properties();
    if (NULL == properties) {
        fprintf(stderr, "Failed to initialize the properties.");
        return 1;
    }

    // 向事件属性添加用户的注册渠道
    assert(SA_OK == sa_add_string("register", "Baidu", 5, properties));

    // 用户注册 ID
    const char* login_id = "abcdefg";

    // 关联注册用户与匿名用户
    assert(SA_OK == sa_track_signup(login_id, anonymous_id, properties, sa));

    // 释放事件属性
    sa_free_properties(properties);

注意,对同一个用户,sa_track_signup() 一般情况下建议只调用一次(通常在用户 注册 时调用),用户 登录 前后的行为的关联建议在业务端实现。在神策分析 1.13 版本之前,多次调用 sa_track_signup() 时,只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参考 如何准确的标识用户,并在必要时联系我们的技术支持人员。

5. 设置用户属性

为了更准确地提供针对人群的分析服务,神策分析 SDK 可以设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。使用

// 设置用户属性,如果某个属性已经在该用户的属性中存在,则覆盖原有属性
//
// @param distinct_id<in>       用户 ID
// @param properties<in>        用户属性
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 设置成功,否则失败
#define sa_profile_set(distinct_id, properties, sa)

设置用户属性,例如在电商应用中,用户注册时,填充了一些个人信息,可以用Profile接口记录下来:

    properties = sa_init_properties();
    if (NULL == properties) {
        fprintf(stderr, "Failed to initialize the properties.");
        return 1;
    }

    // 用户的注册渠道
    assert(SA_OK == sa_add_string("register", "Baidu", 5, properties));
    // 用户注册日期
    assert(SA_OK == sa_add_date("$signup_time", time(NULL), 0, properties));
    // 用户是否购买过商品
    assert(SA_OK == sa_add_bool("is_vip", SA_FALSE, properties));
    //  $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 SA_TRUE,否则为 SA_FALSE,默认为 SA_FALSE
    assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);

    // 设置用户属性
    assert(SA_OK == sa_profile_set(login_id, properties, sa));

    sa_free_properties(properties);

对于不再需要的用户的一个属性,可以通过

// 删除某用户的一个属性
//
// @param distinct_id<in>       用户 ID
// @param key<in>               用户属性名称
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 设置成功,否则失败
#define sa_profile_unset(distinct_id, key, sa)

接口将属性删除。也可以通过

// 删除某用户所有属性
//
// @param distinct_id<in>       用户 ID
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 设置成功,否则失败
#define sa_profile_delete(distinct_id, sa)

接口将某个用户的所有属性删除。

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

5.1 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用

// 设置用户属性,如果某个属性已经在该用户的属性中存在,则忽略该操作
//
// @param distinct_id<in>       用户 ID
// @param properties<in>        用户属性
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 设置成功,否则失败
#define sa_profile_set_once(distinct_id, properties, sa)

接口记录这些属性。与 sa_profile_set() 接口不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据>,如果属性不存在则会自动创建。因此,sa_profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:

    // 记录用户首次登陆时间
    properties = sa_init_properties();
    if (NULL == properties) {
        fprintf(stderr, "Failed to initialize the properties.");
        return 1;
    }

    // 用户首次使用时间
    assert(SA_OK == sa_add_date("first_time", time(NULL), 0, properties));

    //  $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 SA_TRUE,否则为 SA_FALSE,默认为 SA_FALSE
    assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);

    // 记录用户属性
    assert(SA_OK == sa_profile_set_once(cookie_id, properties, sa));

    sa_free_properties(properties);

5.2 数值类型的属性

对于数值型的用户属性,可以使用

// 增加或减少用户属性中的 Number 类型属性的值
//
// @param distinct_id<in>       用户 ID
// @param properties<in>        用户属性,必须为 Number 类型的属性
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 设置成功,否则失败
#define sa_profile_increment(distinct_id, properties, sa)

对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如:

    // 在用户属性中记录用户支付金额
    properties = sa_init_properties();
    if (NULL == properties) {
        fprintf(stderr, "Failed to initialize the properties.");
        return 1;
    }

    // 累加用户支付金额
    assert(SA_OK == sa_add_number("pay", 5888, properties));
    // 用户获得头衔
    assert(SA_OK == sa_append_list("title", "VIP", 3, properties));

    // 记录搜索商品事件
    assert(SA_OK == sa_profile_increment(login_id, properties, sa));

    sa_free_properties(properties);

5.3 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性,可以通过

// 向用户属性中的 List 属性增加新元素
//
// @param distinct_id<in>       用户 ID
// @param properties<in>        用户属性,必须为 List 类型的属性
// @param sa<in/out>            SensorsAnalytics 对象
//
// @return SA_OK 设置成功,否则失败
#define sa_profile_append(distinct_id, properties, sa)

接口记录列表型属性。需要注意的是,列表型属性中的元素必须为 String 类型,且元素的值会自动去重。关于列表类型限制请见 数据格式 7.3 属性长度限制

接口样例请参考前一节中的代码。