1. 用户关联

1.1. 用户登录

当用户注册成功或者登录成功时，需要调用 SDK 的 - login: 接口

sensorsdata::SensorsAnalytics::login("<#登录 id#>")

CODE

为了准确记录登录用户的行为信息，建议在以下时机各调用一次 - login：接口

用户在注册成功时
用户登录成功时
已登录用户每次启动 App 时

2. 用户属性

注意

关于事件属性和用户属性的区别，请参考数据模型
用户属性的命名约束，请参考数据格式

2.1. 设置用户属性

-profileSet: 方法可以设置用户属性，同一个 key 多次设置时，value 值会进行覆盖替换：

// 设定用户年龄属性 "Age" 为 18
sensorsdata::ObjectNode usersProperties;
usersProperties.setNumber("Age", 18);
sensorsdata::SensorsAnalytics::profileSet(usersProperties);

CODE

2.2. 记录初次设定的用户属性

对于只在首次设置时有效的属性，我们可以使用 profileSetOnce 记录这些属性。与 profileSet 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce 适用于为用户设置首次激活时间、首次注册时间等属性。例如：

// 设定用户渠道为 "developer@sensorsdata.cn" 的 "AdSource" 属性值为 "XXX Store"
sensorsdata::ObjectNode usersProperties;
usersProperties.setString("AdSource", "XXX Store");
sensorsdata::SensorsAnalytics::profileSetOnce(usersProperties);
 // 再次设定用户渠道，设定无效， "AdSource" 属性值仍然是 "XXX Store" sensorsdata::ObjectNode usersProperties;
sensorsdata::ObjectNode usersProperties;
usersProperties.setString("AdSource", "Email");
sensorsdata::SensorsAnalytics::profileSetOnce(usersProperties);

CODE

3. 埋点事件采集

在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。

3.1. 代码埋点追踪事件

SDK 初始化后，可以通过 -track: 方法追踪用户行为事件，并为事件添加自定义属性。

其中对应的事件名为：BuyProduct; 对应的事件自定义属性为 ProductID 和 UserLevel；

sensorsdata::ObjectNode eventProperties;
// 设置商品类别
eventProperties.setString("ProductCatalog", "Laptop Computer");
// 设置商品 ID
eventProperties.setNumber("ProductID", 3);
sensorsdata::SensorsAnalytics::track("BuyProduct", eventProperties);

CODE

注意

事件名和事件属性的格式规范，请参考数据格式。

3.2. 埋点事件采集时长属性

可以通过计时器统计事件的持续时间。首先，在事件开始时调用 -trackTimerStart: ，该方法并不会真正发送事件；在事件结束时，调用 -trackTimerEnd: ，SDK 会触发 "Event" 事件，并自动将事件持续时间记录在事件属性 "$event_duration" 中。例如记录用户浏览商品页面的时间：

sensorsdata::SensorsAnalytics::trackTimerStart("ViewProduct");
sensorsdata::ObjectNode eventProperties;
// 设置商品类别
eventProperties.setString("ProductCatalog", "Laptop Computer");
// 设置商品 ID
eventProperties.setNumber("product_id", 3);
sensorsdata::SensorsAnalytics::trackTimerEnd("ViewProduct", eventProperties);

CODE

多次调用 -trackTimerStart: 时，事件的开始时间以最后一次调用时为准。注意务必确保 trackTimerStart 和 trackTimerEnd 接口配对使用，多次调用 -trackTimerEnd: 会触发无时长的埋点事件。
统计事件时长支持暂停和恢复，通过调用 -trackTimerPause: 和 -trackTimerResume: 来分别实现暂停和恢复。如果需要清空已记录的时长事件则调用 -clearTrackTimer: 接口。

3.3. 物品元数据上报

3.3.1. 设置物品属性

直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考数据格式。

sensorsdata::ObjectNode itemProperties;
// 设置商品类别
eventProperties.setString("ProductCatalog", "Laptop Computer");
// 设置商品 ID
eventProperties.setNumber("product_id", 3);
sensorsdata::SensorsAnalytics::itemSet("itemType", "itemId", itemProperties);

CODE

3.3.2. 删除物品属性

如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。除物品 ID 与物品所属类型外，不解析其他物品属性。

sensorsdata::SensorsAnalytics::itemDelete("itemType", "itemId");

CODE

4. 事件属性

在进行埋点事件追踪时，您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性，同时公共属性又分为静态公共属性和动态公共属性。静态公共属性用于设置更新频率较低的属性，动态公共属性用于设置更新频率高的属性。当同一事件中出现相同 Key 的属性时，SDK 覆盖优先级：预置属性 < 静态公共属性 < 动态公共属性 < 自定义属性。

4.1. 静态公共属性

静态公共属性是指对于所有事件都需要添加的属性，初始化 SDK 后，可以通过 -registerSuperProperties: 将属性注册为公共属性。设置方法如下:

// 将应用名称作为事件公共属性，后续所有追踪的事件都会自动带上 "AppName" 属性
sensorsdata::ObjectNode superProperties;
// 设置商品类别
eventProperties.setString("AppName", "AppName");
sensorsdata::SensorsAnalytics::registerSuperProperties(superProperties);

CODE

注意

公共属性会保存在 App 本地缓存中，可以通过 - unregisterSuperProperties: 删除一个或多个公共属性；或使用 - clearSuperProperties: 删除所有已经设置的事件公共属性。

5. 数据存储与发送

需要更精细地控制神策分析可以通过以下选项设置数据采集功能。

5.1. 数据采集

在每次调用 -track: 、-login:、-profileSet: 等方法时，神策分析 SDK 会将埋点事件保存在数据库中，并会检查如下条件，以判断是否向服务器上传数据:

是否是 WIFI/2G/3G/4G/5G 网络条件
是否满足发送条件之一:
1. 与上次发送的时间间隔是否大于 flushInterval
2. 本地缓存日志数目是否大于 flushBulkSize
3. 事件类型为 login() 方法触发的 $SignUp 事件

默认的 flushBulkSize 为 100 条，默认的 flushInterval 为 15 秒。满足条件后，神策分析 SDK 会将数据 gzip 压缩后，批量发送到神策分析。

如果追求数据采集的时效性，可以调用 -flush: 方法，强制将数据发送到神策分析，例如：

// 记录用户登录事件 
sensorsdata::SensorsAnalytics::track("UserLogin");

// 强制发送数据 
sensorsdata::SensorsAnalytics::flush();

CODE

在 App 进入后台状态时，SDK 会调用 -flush: 方法，将缓存的数据发送到神策分析。

5.2. 设置发送数据的网络策略

默认情况下，在 WIFI/3G/4G/5G 网络条件下，SDK 都会尝试去同步数据。 sensors.setFlushNetworkPolicy() 方法来指定发送数据的网络策略。例如：

//指定只在 3G/4G/WIFI 条件下发送数据。
sensorsdata::SensorsAnalytics::setFlushNetworkPolicy(kFlush3G|kFlush4G|kFlushWiFi);

CODE

5.3. 清空本地缓存事件

可以通过 deleteAll() 方法，删除 App 本地存储的所有事件。

如果不是特殊要求，请不要调用此方法。

//删除 App 本地存储的所有事件 
sensorsdata::SensorsAnalytics::.deleteAll();

CODE

6. 全埋点

cocox2d-x 支持 $AppStart（App 启动）、$AppEnd（App 退出）两种全埋点事件。
Android SDK 为了应对多进程、强杀等场景，加入了 30 秒的 session 机制，用户退出 App 到后台 30 秒的时候，才会触发退出事件，之后再启动 App，才会触发启动事件，用户如果在 30 秒内打开了 App，那么是没有对应的退出事件与启动事件的。另外，如果在退出 App 到后台 30 秒内，进程还没有被杀掉，那么此时会触发退出事件并尝试上报，如果进程被杀掉了，那么退出事件会在下一次启动时补发。所以在查看数据时，一般退出事件比启动事件少。

6.1. 开启全埋点

SDK 可以自动采集一些用户行为，如 App 启动、退出。初始化 SDK 时，可以配置需要开启的全埋点类型：

String SA_SERVER_URL = "数据接收地址";
 
// 初始化配置
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// 开启全埋点「启动、退出」
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_START |
                SensorsAnalyticsAutoTrackEventType.APP_END);
 
// 需要在主线程初始化神策 SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);

CODE

// 引入神策分析 SDK
#import <SensorsAnalyticsSDK/SensorsAnalyticsSDK.h>
 
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
 
    // 初始化配置
    SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
    // 开启全埋点「启动、退出」 
    options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
                                 SensorsAnalyticsEventTypeAppEnd;
 
    // 初始化 SDK
    [SensorsAnalyticsSDK startWithConfigOptions:options];
    ...
    return YES;
}

CODE