1. 用户关联

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

2. 用户属性

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

2.1. 设置用户属性

使用 setProfile() 方法设置用户属性，该方法对已设置的属性再次设置会覆盖已有数据。

// 设定用户的 "AdSource" 属性值为 "XXX Store"
sensors.setProfile({ AdSource: "XXX Store"	})

CODE

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

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

// 设定用户的 "AdSource" 属性值为 "XXX Store"
sensors.setOnceProfile({ AdSource: "XXX Store"	})
// 再次设定用户渠道，设定无效， "AdSource" 属性值仍然是 "XXX Store"
sensors.setOnceProfile({ AdSource : "Email" })

CODE

2.3. 数值类型的属性

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

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

CODE

2.4. 列表类型的属性

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

// 设定用户观影列表属性，设定后属性 "Movies" 为: ["Sicario", "Love Letter"]
sensors.appendProfile('Movies', ['Sicario','Love Letter']);

CODE

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

2.5. 删除用户属性

如果需要删除已设置的某个用户属性，可以调用 unsetProfile() 进行删除：

sensors.unsetProfile("age");

CODE

2.6. 删除用户

删除当前用户及他的所有属性。

//删除当前这个用户及他的所有属性
sensors.deleteProfile();

CODE

3. 埋点事件采集

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

3.1. 代码埋点追踪事件

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

//触发一条 BuyProduct 事件，同时设置商品 ID、商品类别属性
sensors.track('BuyProduct', { ProductID: 123456, ProductCatalog:'Laptop Computer'})

CODE

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

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

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

sensors.trackTimerStart('ViewProduct');   
// 调用 track，记录 ViewProduct 事件，并在属性 event_duration 中记录用户浏览商品的时间
sensors.trackTimerEnd('ViewProduct', {product_id:'PRODUCT_ID'});

CODE

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

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

3.3. 激活事件采集

可以调用 trackAppInstall() 方法记录激活事件，多次调用此方法只会在第一次调用时触发激活事件，仅支持 Android&iOS 端。

sensors.trackAppInstall({propA:'valueA'});

CODE

若用原记录的激活事件名不是 $AppInstall，需要使用虚拟事件将原激活事件和 $AppInstall 合并分析数据，具体咨询神策技术支持
更多关于渠道追踪功能的说明，请参考渠道追踪。

4. 事件属性

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

4.1. 公共属性

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

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

CODE

通过 unRegister(key:String) 方法删除指定 key 的公共属性。

通过 clearRegister() 方法删除所有注册的公共属性。

5. 数据存储与发送

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

5.1. 数据采集

在每次调用 track()、setProfile() 等方法时，神策分析 SDK 会将埋点事件保存在数据库中（该特性仅在编译为 Android 和 iOS 时生效，不支持 Web），达到发送条件（满足缓存数目或缓存时间间隔并且有网络连接）后神策分析 SDK 会将数据 gzip 压缩后，批量发送到神策分析。

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

// 记录用户登录事件
sensors.track("Pay");

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

CODE

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

注意：login 方法触发 $SignUp 事件时会立即触发将缓存的数据发送到神策分析。

5.2. 清空本地缓存事件

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

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

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

CODE

6. 全埋点

全埋点是指 APP 端： $AppStart（App 启动）、$AppEnd（App 退出）、$AppViewScreen（浏览页面）和 $AppClick（控件点击）四种事件。Web 端：$pageview（页面浏览）、$WebClick（元素点击）、$WebStay（页面滚动）三种事件。
针对 App 启动和退出，Android SDK 为了应对多进程、强杀等场景，加入了 30 秒的 session 机制，用户退出 App 到后台 30 秒的时候，才会触发退出事件，之后再启动 App，才会触发启动事件，用户如果在 30 秒内打开了 App，那么是没有对应的退出事件与启动事件的。另外，如果在退出 App 到后台 30 秒内，进程还没有被杀掉，那么此时会触发退出事件并尝试上报，如果进程被杀掉了，那么退出事件会在下一次启动时补发。所以在查看数据时，一般退出事件比启动事件少。

6.1. 开启全埋点配置

SDK 可以自动采集一些用户行为，如 App 启动、退出、浏览页面（要求必须在初始化 SDK 前调用 SDK useRouter 方法才可以自动采集）、控件点击。初始化 SDK 时，可以配置需要开启的全埋点类型：

sensors.init({
	//... 其他配置        
  	web: {//web 初始化配置
       page_view: true, // 自动采集 $pageview（页面浏览）
       web_click: true, // 自动采集 $WebClick（元素点击）
       web_stay: true,  // 自动采集 $WebStay（页面滚动停留时长） 
    },
	app: {// Android & iOS 配置
       app_start: true,   // 自动采集 App 启动
       app_end: true,     // 自动采集 App 退出
       view_screen: true, // 自动采集浏览页面
       view_click: true   // 自动采集控件点击
	} 
})

CODE

如果使用 scroller 控件作为页面最外层，编译为 web 项目时将无法自动上报 $WebStay。

6.2. useRouter 方法

为了实现自动采集页面浏览事件（$AppViewScreen、$pgeview），需要在初始化 SDK 前调用 SDK 提供的 useRouter 方法并传入页面所在的 VueRouter 对象。目前仅支持 VUE 进行开发的 Weex 应用，不支持 Rax。

// 步骤1: 引入模块
import sensors from 'sa-sdk-weex'
 
// 步骤2: 将项目中声明对 VueRouter 对象传入 Weex SDK 提供的 useRouter 方法以支持页面切换时自动采集页面浏览事件
const { router } = require('./router')
sensors.useRouter(router)

CODE

6.3. 手动触发全埋点事件

手动触发全埋点事件是指由开发者主动调用 SDK 提供的接口触发 App 页面浏览事件，与 SDK 自动触发的全埋点事件的区别是开发者调用接口触发的全埋点事件 lib_method 取值为 code，由 SDK 触发的全埋点事件取值为 autoTrack，注意该功能建议不要与全埋点重复混合使用，防止事件重复。

6.3.1. 手动触发页面的浏览事件

通过 trackViewScreen() 方法可以手动触发 App 页面浏览事件，并且该接口不受忽略等条件的限制。

sensors.trackViewScreen(url, {title:'title'})

CODE

7. 其他功能

7.1. 设置数据上报地址

调用 setServerUrl 来修改数据上报地址，调用成功之后数据将以新的数据上报地址进行上报。

sensors.setServerUrl('数据接收地址');

CODE