1. 封装接口

这里定义了一个 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
CODE

2. 追踪事件

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

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

用户通过

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

接口记录事件。开发者必须传入用户 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
CODE

2.1. 事件属性

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

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

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

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

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

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

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

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

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

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

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

// 向事件属性或用户属性的 List 类型的属性中插入新对象,对象必须是 String 类型的
//
// @param key<in>          属性名称
// @param string<in>       字符串的句柄
// @param length<in>       字符串长度
// @param properties<out>  SAProperties 对象
//
// @return SA_FFI_OK 添加成功,否则失败
function _M.sa_append_list(key, string, length, properties)
CODE

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

2.1.1. 系统预置属性

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

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

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

3. 用户识别

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

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

3.1. 用户注册/登录

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

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

将旧的 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
CODE

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

4. 设置用户属性

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

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

设置用户属性,例如在电商应用中,用户注册时,填充了一些个人信息,可以用 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
CODE

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

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

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

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

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

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

4.1. 记录初次设定的属性

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

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

接口记录这些属性。与 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
CODE

4.2. 数值类型的属性

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

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

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

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
CODE

4.3. 列表类型的属性

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

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

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