1. 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 Divine Analysis. 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 对象，NULL 表示无事件属性 // @param sa<in/out> SensorsAnalytics 实例 // // @return SA_OK 追踪成功，否则追踪失败 #define 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, marking the user and the event name, while the developer can pass one in the third parameter SAProperties object, add custom event properties to the event, use NULL The user-defined event attribute must contain 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:

// 记录用户提交订单事件 // 初始化事件属性 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);

1.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 Sensors analytics:

• The event attribute is one 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  value of the element is the value of the event attribute, support String、Number、Bool、List 和 Date, For more constraints on event attributes in Sensors analytis, see Data format.

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

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

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 number_<in> 属性值 // @param properties<out> SAProperties 对象 // // @return SA_OK 添加成功，否则失败 int sa_add_number(const char* key, double number_, SAProperties* properties);

Adds an attribute of type Date where the first argument is a timestamp in seconds, such as a system function time(NULL) the return value and the second argument is the millisecond part:

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

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_OK 添加成功，否则失败 int sa_add_string( const char* key, const char* string_, unsigned int length, SAProperties* 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_OK 添加成功，否则失败 int sa_append_list( const char* key, const char* string_, unsigned int length, SAProperties* properties);

For details, see the example in the previous section.

1.1.1. System preset attribute

For example, the attributes starting with '$' in the event attribute 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 attribute:

• $ip - Use sa_add_string() 向 SAProperties object added to this attribute, the user's province and city information will be automatically resolved based on the IP address.
• $time - Use sa_add_date() 向 SAProperties object 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.

2. 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.

2.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_OK 追踪关联事件成功，否则失败 #define 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 ... // 用户未注册前的匿名 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);

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 advised to implement the behavior association on the service end. Called multiple times before the 1.13 version of Sensors Analytics sa_track_signup() , 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 Identifying Users - Easy User Association (IDM 2.0 & IDM 1.0) and contact our technical support staff if necessary.

3. Set user properties

In order to provide more accurate analysis services for the population, the 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_OK 设置成功，否则失败 #define 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:

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

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_OK 设置成功，否则失败 #define sa_profile_unset(distinct_id, key, sa)

The interface deleted the attribute. Can also use

// 删除某用户所有属性 // // @param distinct_id<in> 用户 ID // @param sa<in/out> SensorsAnalytics 对象 // // @return SA_OK 设置成功，否则失败 #define 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.

3.1. Record the properties that were first set

We can use properties that are only valid when first set

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

The interface records these attributes. Different from  sa_profile_set() interface, If the set user property already exists, the record is ignored without overwriting existing data, and is automatically created if the property does not exist. Therefore,sa_profile_set_once() comparison applies to setting attributes such as the first activation time and first registration time. For example:

// 记录用户首次登录时间 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);

3.2. Numeric Type Property

For numeric user properties, you can use

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

to accumulate the property values. It is commonly used to record user payment frequency, payment amount, points, and other attributes. For example:

// 在用户属性中记录用户支付金额 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);

3.3. List Type Property

For properties such as movies that users like or restaurants they have reviewed, you can use the

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

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.