基础 API 介绍（C）

追踪事件

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

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

用户通过

// 跟踪一个用户的行为
//
// @param distinct_id      用户 ID
// @param event            事件名称
// @param properties       事件属性，SAProperties 对象，NULL 表示无事件属性
// @param sa           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);

事件属性

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

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

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

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

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

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

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

// 向事件属性或用户属性添加 Date 类型的属性
//
// @param key           属性名称
// @param seconds       时间戳，单位为秒
// @param microseconds  时间戳中毫秒部分
// @param properties   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           属性名称
// @param string_       字符串的句柄
// @param length        字符串长度
// @param properties   SAProperties 对象
//
// @return SA_OK 添加成功，否则失败
int sa_add_string(
        const char* key,
        const char* string_,
        unsigned int length,
        SAProperties* properties);

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

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

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

系统预置属性

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

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

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

用户识别

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

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

用户注册/登录

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

// 关联匿名用户和注册用户
//
// @param distinct_id       用户的注册 ID
// @param origin_id         被关联的用户匿名 ID
// @param properties        事件属性
// @param sa            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", "AAA", 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 关联的方法。更详细的说明请参考标识用户——简易用户关联（IDM 2.0 & IDM 1.0），并在必要时联系我们的技术支持人员。

设置用户属性

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

// 设置用户属性，如果某个属性已经在该用户的属性中存在，则覆盖原有属性
//
// @param distinct_id       用户 ID
// @param properties        用户属性
// @param sa            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", "AAA", 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       用户 ID
// @param key               用户属性名称
// @param sa            SensorsAnalytics 对象
//
// @return SA_OK 设置成功，否则失败
#define sa_profile_unset(distinct_id, key, sa)

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

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

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

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

记录初次设定的属性

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

// 设置用户属性，如果某个属性已经在该用户的属性中存在，则忽略该操作
//
// @param distinct_id       用户 ID
// @param properties        用户属性
// @param sa            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);

数值类型的属性

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

// 增加或减少用户属性中的 Number 类型属性的值
//
// @param distinct_id       用户 ID
// @param properties        用户属性，必须为 Number 类型的属性
// @param sa            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);

列表类型的属性

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

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

接口记录列表型属性。需要注意的是，列表型属性中的元素必须为 String 类型。关于列表类型限制请见 数据格式 属性长度限制。