1. Encapsulated interface

Here we define a table that encapsulates C SDK-related interfaces:

-- 定义一个 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

2. Trace event

For the first time, it is recommended to track 3 to 5 key events, and it only takes a few lines of code to experience the analysis function of Sensors Analytics. For example:

• Photo social products that track users browsing pictures and commenting on events
• E-commerce products can track events such as user registration, browsing products and placing orders

User use

// 跟踪一个用户的行为 // // @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)

The interface records events. Procedure The developer must pass in the user ID（distinct_id）and event name（event）two parameters，mark the user and event names, while the developer can pass one in as the third parameter SAProperties object, add a custom event attribute to an event that contains the $is_login_id attribute to specify whether the distinct_id is a login ID. Taking e-commerce products as an example, you can track a purchase like this:

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

2.1. Event attribute

As the example in the previous article, the developer can customize the attributes of the event tracking, for example, the product ID, product classification and other information as the event attributes. In the subsequent analysis work, the event attribute can be used as a statistical filter condition or as a dimension for multidimensional analysis. For event attributes, there are some constraints on divine analysis:

• The event attribute is  SAProperties object, The SDK provides interfaces that are initialized and released by the developer;
• SAProperties Each element describes an event attribute. The attribute name must be a string, start with uppercase and lowercase letters, consist of letters and numbers, and cannot exceed 100 characters.
• SAProperties The value of the element is the value of the event attribute String、Number、Bool、List and Date，for more constraints on event attributes in strategy analysis, see data format.

Developers can use the following interface to SAProperties to add an attribute value to an object, for example, adding an attribute of type Bool:

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

The attribute name must be a string of letters and digits that starts with a uppercase letter and cannot exceed 100 characters. Add attributes of type Number:

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

Adds an attribute of type Date, where the first argument is a timestamp in seconds and the second argument is a millisecond part:

// 向事件属性或用户属性添加 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) 

Add the String attribute, the string must be UTF-8 encoding, the string length is the actual UTF-8 length, such as a Chinese character takes 3 bytes:

// 向事件属性或用户属性添加 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)

Add a String object to an attribute of type List:

// 向事件属性或用户属性的 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)

For details, see the example in the previous section.

2.1.1. System preset attribute

As the example in the previous article, The attributes starting with '$' in the event attributes are preset attributes of the system. You can override these preset attributes by filling in the corresponding attribute value starting with '$' in the user-defined event attributes:

• $ip - use sa_add_string() in SAProperties When the object is added to this attribute, the user's province and city information will be automatically resolved based on the IP address.
• $time - 通过 sa_add_date()  SAProperties The object is added to the property, and the analysis sets the event time to the time of the property value. Please note that by default, Analytics filters out data that is more than 2 years old or 1 hour old. If you need to change this limit, please contact our technical support.

For more preset properties, see data format In the 'Preset Properties' section.

3. User identification

In the server-side application, the Distinct Id of the user is also required to be set for each event, which helps the analytics provide more accurate data such as retention rates.

For registered users, a user ID in the system is recommended as a Distinct Id. Modified information such as the user name, Email address, and mobile phone number are not recommended.

3.1. User registration/login

When the Distinct Id of the same user changes (usually due to anonymous user registration behavior), you can perform the following operations:

// 关联匿名用户和注册用户 // // @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)

Associate the old Distinct Id with the new Distinct Id to ensure the accuracy of user analysis. For example:

-- 初始化神策分析 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

Note that for the same user,sa_track_signup() In general, it is recommended to call only once (usually at the user register call）, user login You are advised to implement the behavior association on the service end. Called multiple times before the 1.13 version of Divine Analysis sa_track_signup() When only the first association behavior is valid. The method for multi-device id association was provided after the 1.13 version of Divine Analysis. Please refer to more detailed instructions Identify users - Easy user association（IDM 2.0 & IDM 1.0）, and contact our technical support staff if necessary.

4. Set user properties

In order to provide more accurate analysis services for the population, the Sensors Analytics SDK can set user attributes, such as age, gender, and so on. Users can use user attributes as filtering criteria or user attributes as dimensions for multi-dimensional analysis in retention analysis, distribution analysis and other functions. Use

// 设置用户属性，如果某个属性已经在该用户的属性中存在，则覆盖原有属性 // // @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)

Set user attributes, for example, in an e-commerce application, when a user registers, some personal information is filled, which can be recorded using the Profile interface:

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

For user attributes that are no longer needed, you can use

// 删除某用户的一个属性 // // @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)

The interface deleted the description of attribute. Can also use

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

This interface deletes all the attributes of a user.

In user attributes, the constraints on the attribute name and attribute value are the same as those on event attributes. For details, see data format.

4.1. Records the properties that were first set

For properties that are only valid when initially set, we can use

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

interface to record these properties. Different from the sa_profile_set() interface, if the set user property already exists, this record will be ignored and existing data will not be overwritten. If the property does not exist, it will be automatically created. Therefore, sa_profile_set_once() is more suitable for setting properties such as first activation time and first registration time for users. For example:

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

4.2. Numerical properties

For numerical user properties,

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

can be used to accumulate the property values. It is commonly used to record properties such as the number of payments, payment amounts, and points. For example:

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

4.3. can be used to record list-type properties such as movies that users like or restaurants they have reviewed. It should be noted that the elements in the list type property must be of type String. For the limitations on list types, please refer to data format property length limit.

For the user's favorite movie, the user has reviewed the restaurant and other attributes, you can use

// 向用户属性中的 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)

Interface record column phenotype attributes. Note that the element in the column phenotype attribute must be String type. See list type restrictions data format Attribute length restriction.