# C SDK

> ### *在使用前，请先阅读*[*数据模型*](https://54td.gitbook.io/shence/technical_guide/data_import/data_model)*的介绍。*

## 1. 集成神策分析 SDK

开发者可以在 C 程序中集成 [神策分析 SDK](https://github.com/sensorsdata/sa-sdk-c)，使用神策分析采集并分析用户数据。

从 Github 下载 [神策分析 SDK](https://github.com/sensorsdata/sa-sdk-c) 的源代码，可在本地编译，通过静态库的形式加入项目中，也可以直接将源文件引入项目中。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 工具](https://54td.gitbook.io/shence/technical_guide/import_tool/log_agent) 将日志文件传输到神策分析中。[LogAgent 工具](https://54td.gitbook.io/shence/technical_guide/import_tool/log_agent) 保证日志传输的时效性和完整性。

## 2. 初始化神策分析 SDK

在程序中使用

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

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

```c
// 初始化 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` 实例，它负责将用户行为日志输出到本地磁盘。

```c
    // 初始化 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 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：

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

用户通过

```c
// 跟踪一个用户的行为
//
//  @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。以电商产品为例，可以这样追踪一次购物行为：

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

    // 初始化事件属性
    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` 中元素的值为事件属性值，支持 `String`、`Number`、`Bool`、`List` 和 `Date`，对于神策分析中事件属性的更多约束，请参考 [数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema)。

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

```c
// 向事件属性或用户属性添加 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 类型的属性：

```c
// 向事件属性或用户属性添加 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)` 的返回值，第二个参数为毫秒部分：

```c
// 向事件属性或用户属性添加 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 个字节：

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

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

```c
// 向事件属性或用户属性的 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 小时后的数据，如需修改这个限制请联系我们的技术支持。

关于其他更多预置属性，请参考 [数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema) 中 '预置属性' 一节。

## 4. 用户识别

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

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

### 4.1 用户注册/登录

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

```c
// 关联匿名用户和注册用户
//
// @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 关联，以保证用户分析的准确性。例如：

```c
    // 初始化神策分析 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 关联的方法。更详细的说明请参考 [如何准确的标识用户](https://54td.gitbook.io/shence/technical_guide/data_import/user_identify)，并在必要时联系我们的技术支持人员。

## 5. 设置用户属性

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

```c
// 设置用户属性，如果某个属性已经在该用户的属性中存在，则覆盖原有属性
//
// @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接口记录下来:

```c
    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);
```

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

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

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

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

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

用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 [数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema)。

### 5.1 记录初次设定的属性

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

```c
// 设置用户属性，如果某个属性已经在该用户的属性中存在，则忽略该操作
//
// @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()` 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如：

```c
    // 记录用户首次登陆时间
    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 数值类型的属性

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

```c
// 增加或减少用户属性中的 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)
```

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

```c
    // 在用户属性中记录用户支付金额
    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 列表类型的属性

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

```c
// 向用户属性中的 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` 类型，且元素的值会自动去重。关于列表类型限制请见 [**数据格式**](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema) **7.3 属性长度限制**。

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