基础 API 介绍（Lua）

封装接口

这里定义了一个 table，用于封装 C SDK 相关接口：

-- 定义一个 table，用于封装 C SDK 相关接口
local _M = new_tab(0, 16)

_M.version = "0.0.1"
_M.new_tab = new_tab
_M.clear_tab = clear_tab

_M.FFI_OK = 0
_M.FFI_RESULT_ERROR = 1
_M.FFI_INVALID_PARAMETER_ERROR = 2

追踪事件

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

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

用户通过

// 跟踪一个用户的行为
//
// @param distinct_id      用户ID
// @param event            事件名称
// @param properties       事件属性，SAProperties 对象
// @param sa           SensorsAnalytics 实例
//
// @return SA_FFI_OK 追踪成功，否则追踪失败.
function _M.sa_track(distinct_id, event, properties, sa)

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

do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- 通过请求中的 UA，可以解析出用户使用设备的操作系统是 iOS 的.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("$os", "iOS", strlen("iOS"), properties))
    -- 操作系统的具体版本.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties))
    -- 请求中能够拿到用户的 IP，则把这个传递给 SA，SA 会自动根据这个解析省份、城市.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties))
    -- 商品名称.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("product_name", "XX手机", 8, properties))
    -- 商品价格.
    assert(SA_FFI_OK == sensors_analytics.sa_add_int("product_price", 5888, properties))
    -- 商品折扣.
    assert(SA_FFI_OK == sensors_analytics.sa_add_number("product_discount", 0.8, properties))
    -- 记录购买商品事件.
    assert(SA_FFI_OK == sensors_analytics.sa_track(cookie_id, "SubmitOrder", properties, sa))

    sensors_analytics.sa_free_properties(properties)
end

事件属性

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

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

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

// 向事件属性或用户属性添加 Bool 类型的属性
//
// @param key           属性名称
// @param value         属性值
// @param properties   SAProperties 对象
//
// @return SA_FFI_OK 添加成功，否则失败.
function _M.sa_add_bool(key, value, properties)

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

// 向事件属性或用户属性添加 Number 类型的属性
//
// @param key           属性名称
// @param value         属性值
// @param properties   SAProperties 对象
//
// @return SA_FFI_OK 添加成功，否则失败.
function _M.sa_add_number(key, value, properties)

加入 Date 类型的属性，其中第一个参数为单位为秒的时间戳，第二个参数为毫秒部分：

// 向事件属性或用户属性添加 Date 类型的属性
//
// @param key           属性名称
// @param seconds       时间戳，单位为秒
// @param microseconds  时间戳中毫秒部分
// @param properties   SAProperties 对象
//
// @return SA_FFI_OK 添加成功，否则失败
function _M.sa_add_date(key, seconds, microseconds, properties)

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

// 向事件属性或用户属性添加 String 类型的属性
//
// @param key          属性名称
// @param string       字符串的句柄
// @param length       字符串长度
// @param properties  SAProperties 对象
//
// @return SA_FFI_OK 添加成功，否则失败
function _M.sa_add_string(key, string, length, properties)

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

// 向事件属性或用户属性的 List 类型的属性中插入新对象，对象必须是 String 类型的
//
// @param key          属性名称
// @param string       字符串的句柄
// @param length       字符串长度
// @param properties  SAProperties 对象
//
// @return SA_FFI_OK 添加成功，否则失败
function _M.sa_append_list(key, string, length, 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_FFI_OK 追踪关联事件成功，否则失败
function _M.sa_track_signup(distinct_id, origin_id, properties, sa)

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

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

-- 用户未登录时，可以使用产品自己生成的 cookieId 来标注用户.
local cookie_id = "ABCDEF123456789"

-- 用户注册 ID
local login_id = "123456"

-- 通过 track_signup 把匿名 ID 和注册 ID 关联起来.
do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- 用户的注册渠道.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("register", "AAA", 5, properties))
    -- 关联注册用户与匿名用户.
    assert(SA_FFI_OK == sensors_analytics.sa_track_signup(login_id, cookie_id, properties, sa))

    sensors_analytics.sa_free_properties(properties)
end

注意，对同一个用户，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_FFI_OK 设置成功，否则失败
function _M.sa_profile_set(distinct_id, properties, sa)

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

do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- 用户的注册渠道.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("register", "AAA", 5, properties))
    -- 用户注册日期.
    assert(SA_FFI_OK == sensors_analytics.sa_add_date("$signup_time", os.time(), 0, properties))
    -- 用户是否购买过商品.
    assert(SA_FFI_OK == sensors_analytics.sa_add_bool("is_vip", false, properties))
    -- 设置用户属性.
    assert(SA_FFI_OK == sensors_analytics.sa_profile_set(login_id, properties, sa))

    sensors_analytics.sa_free_properties(properties)
end

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

// 删除某用户的一个属性
//
// @param distinct_id       用户 ID
// @param key               用户属性名称
// @param sa            SensorsAnalytics 对象
//
// @return SA_FFI_OK 设置成功，否则失败
function _M.sa_profile_unset(distinct_id, key, sa)

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

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

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

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

记录初次设定的属性

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

// 设置用户属性，如果某个属性已经在该用户的属性中存在，则忽略该操作
//
// @param distinct_id       用户 ID
// @param properties        用户属性
// @param sa            SensorsAnalytics 对象
//
// @return SA_FFI_OK 设置成功，否则失败
function _M.sa_profile_set_once(distinct_id, properties, sa)

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

do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- 用户首次使用时间.
    assert(SA_FFI_OK == sensors_analytics.sa_add_date("first_time", os.time(), 0, properties))
    -- 记录用户属性.
    assert(SA_FFI_OK == sensors_analytics.sa_profile_set_once(cookie_id, properties, sa))

    sensors_analytics.sa_free_properties(properties)
end

数值类型的属性

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

// 增加或减少用户属性中的 Number 类型属性的值
//
// @param distinct_id       用户 ID
// @param properties        用户属性，必须为 Number 类型的属性
// @param sa            SensorsAnalytics 对象
//
// @return SA_FFI_OK 设置成功，否则失败
function _M.sa_profile_increment(distinct_id, properties, sa)

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

do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- 累加用户支付金额.
    assert(SA_FFI_OK == sensors_analytics.sa_add_int("pay", 5888, properties))
    -- 记录搜索商品事件.
    assert(SA_FFI_OK == sensors_analytics.sa_profile_increment(login_id, properties, sa))

    sensors_analytics.sa_free_properties(properties)
end

列表类型的属性

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

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

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