1. 用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联分为用于支撑不同的业务场景。

2. 用户属性

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

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

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

SensorsAnalyticsFlutterPlugin.profileSetOnce({'AdSource':'XXX Store'});

// 再次设定用户渠道，设定无效，"developer@sensorsdata.cn" 的 "AdSource" 属性值仍然是 "XXX Store"
SensorsAnalyticsFlutterPlugin.profileSetOnce({'AdSource':'developer@sensorsdata.cn'});

CODE

2.2. 数值类型的属性

对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：

// 将用户游戏次数属性增加一次 
SensorsAnalyticsFlutterPlugin.profileIncrement("GamePlayed", 1);

CODE

2.3. 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性，例如：

SensorsAnalyticsFlutterPlugin.profileAppend('address',['Beijing','Shanghai']);

CODE

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

2.4. 属性取消

如果需要取消已设置的某个用户属性，可以调用 profileUnset() 进行取消：

SensorsAnalyticsFlutterPlugin.profileUnset("age");

CODE

3. 埋点事件采集

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

3.1. 代码埋点追踪事件

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

SensorsAnalyticsFlutterPlugin.track('eventname',{'ProductID':'123456','ProductCatalog':'Laptop Computer'});

CODE

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

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

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

// 进入商品页面
// 调用 trackTimerStart("ViewProduct") 标记事件启动时间 
SensorsAnalyticsFlutterPlugin.trackTimerStart("ViewProduct");

// ... 用户浏览商品

// 离开商品页
SensorsAnalyticsFlutterPlugin.trackTimerEnd('ViewProduct',{"product_id":PRODUCT_ID});

CODE

多次调用 trackTimerStart("Event") 时，事件 "Event" 的开始时间以最后一次调用时为准。注意务必确保 trackTimerStart 和 trackTimerEnd 接口配对使用，多次调用 trackTimerEnd 会触发无时长的埋点事件。

统计事件时长支持暂停和恢复，通过调用 trackTimerPause(String eventName) 和 trackTimerResume(String eventName) 来分别实现暂停和恢复。如果需要清空已记录的时长事件则调用 clearTrackTimer() 接口

3.3. 物品元数据上报

3.3.1. 设置物品属性

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

// 为物品类型为 itemType 且物品 ID 为 itemId 的物品，设置物品属性 properties
SensorsAnalyticsFlutterPlugin.itemSet(String itemType, String itemId, [Map<String, dynamic>? properties]);

CODE

3.3.2. 删除物品属性

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

// 删除物品，类型为 itemType，ID 为 itemId
SensorsAnalyticsFlutterPlugin.itemDelete(String itemType, String itemId);

CODE

4. 事件属性

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

4.1. 获取预置属性

可以调用 getPresetProperties() 方法获取预置属性。服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

//获取预置属性 
SensorsAnalyticsFlutterPlugin.getPresetProperties();

CODE

4.2. 静态公共属性

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

// 将应用名称作为事件公共属性，后续所有 track 类型的事件都会自动带上 "AppName" 属性 
SensorsAnalyticsFlutterPlugin.registerSuperProperties({"AppName":"FlutterDemo"});

CODE

注册的静态公共属性可以通过 unregisterSuperProperty(String key) 方法删除指定 key 的静态公共属性，也可以通过 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() 方法，强制将数据发送到神策分析，例如：

// 记录用户登录事件 
SensorsAnalyticsFlutterPlugin.track("UserLogin");

// 强制发送数据 
SensorsAnalyticsFlutterPlugin.flush();

CODE

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

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

默认情况下，在 WIFI/3G/4G/5G 网络条件下，SDK 都会尝试去同步数据。v1.7.2 及以后的版本支持可以自定义同步数据的网络策略。通过 SAConfigOptions.setNetworkTypePolicy() 在初始化时或 SensorsDataAPI.setFlushNetworkPolicy() 方法来指定发送数据的网络策略。例如：

//SANetworkType  为支持的网络类型枚举
SensorsAnalyticsFlutterPlugin.setFlushNetworkPolicy(Set<SANetworkType> networkType)

CODE

5.3. 设置本地缓存上限值

SDK 本地数据库默认缓存数据的上限值根据不同的平台具体值不一样，具体需要在 SensorsAnalyticsFlutterPlugin.init() 方法中配置，如下：

android

AndroidConfig?

其中：

maxCacheSize: 最大缓存数，单位 byte 默认为:32M，即 32* 1024 * 1024

ios

IOSConfig?

其中：

maxCacheSize: 最大缓存数，单位条。默认值：10000