菜单

基础 API 介绍（APICloud）

用户关联

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

用户属性

记录初次设定的用户属性

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

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

数值类型的属性

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

// 将用户游戏次数属性增加一次 
sensorsApiCloudSdk.profileIncrement({
	properties:{chinese:60, math:70}
});

列表类型的属性

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

// 设定用户观影列表属性，设定后属性 "Movies" 为: ["Sicario", "Love Letter"] 
sensorsApiCloudSdk.profileAppend({
	property:'Movies',value: ["Sicario", "Love Letter"] 
});

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

属性取消

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

sensorsApiCloudSdk.profileUnset({
	property:'Movies'
});

埋点事件采集

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

代码埋点追踪事件

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

//触发一条 BuyProduct 事件，同时设置商品 ID、商品类别属性 
sensorsApiCloudSdk.track({
    event:'BuyProduct',
    properties:{
        ProductID:'PRODUCT_ID',
        ProductCatalog:'Laptop Computer',
		ProductPrice: 100
    }
});

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

埋点事件采集时长属性

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

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

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

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

物品元数据上报

设置物品属性

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

// 为物品类型为 itemType 且物品 ID 为 itemId 的物品，设置物品属性  
sensorsApiCloudSdk.itemSet({
	itemType: 'itemType', 
	itemId: 'itemId', 
	properties: {
		itemProperty: 'itemPropertyValue'
	}
});

删除物品属性

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

// 删除物品，类型为 itemType，ID 为 itemId  
sensorsApiCloudSdk.itemDelete({itemType: 'itemType', itemId: 'itemId'});

事件属性

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

获取预置属性

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

//获取预置属性  
var result = sensorsApiCloudSdk.getPresetProperties();

静态公共属性

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

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

注册的静态公共属性可以通过 unregisterSuperProperty 方法删除指定 key 的静态公共属性。

sensorsApiCloudSdk.unregisterSuperProperty({property:'PlatformType'});

数据存储与发送

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

数据采集

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

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

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

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

	// 记录用户登录事件
	sensorsApiCloudSdk.track({
    event:'userLogin',
	    properties:{
        	name:'userName',
        	age:28
    	}
	});
	// 强制发送数据 
	sensorsApiCloudSdk.flush();

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

设置发送数据的网络策略

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

/**
 * 设置 flush 时网络发送策略，默认 3G、4G、WI-FI 环境下都会尝试 flush
 * TYPE_NONE = 0;//NULL
 * TYPE_2G = 1;//2G
 * TYPE_3G = 1 << 1;//3G 2
 * TYPE_4G = 1 << 2;//4G 4
 * TYPE_WIFI = 1 << 3;//WIFI 8
 * TYPE_5G = 1 << 4;//5G 16
 * TYPE_ALL = 0xFF;//ALL 255
 * 例：若需要开启 4G 5G 发送数据，则需要设置 4 + 16 = 20
 */
//指定只在 3G/4G/WIFI 条件下发送数据。 
sensorsApiCloudSdk.setFlushNetworkPolicy({networkPolicy:14});

SDK 网络请求开关

SDK 提供 enableNetworkRequest(boolean isRequest) 的接口用于控制 SDK 的网络请求，参数为 true 表示允许 SDK 发起网络请求，参数为 false 表示禁止 SDK 发起网络请求。注意使用时一定要注意调用时机，防止 SDK 处于禁用网络状态，导致事件无法及时上报。

// 开启网络请求 
sensorsApiCloudSdk.enableNetWorkRequest({isRequest: true }); 
// 禁用网络请求 
sensorsApiCloudSdk.enableNetWorkRequest({isRequest: false });

清空本地缓存事件

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

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

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

全埋点

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

开启全埋点

SDK 可以自动采集一些用户行为，如 App 启动、退出。可在模块配置(config.xml)需要开启：


	...
    
	...

手动触发全埋点事件

手动触发全埋点事件是指由开发者主动调用 SDK 提供的接口触发 App 页面浏览事件。

手动触发页面的浏览事件

通过 trackViewScreen() 方法可以手动触发 App 页面浏览事件。

var argument={url:"https://www.sensorsdata.cn/manual/apicloud_sdk.html",properties:{"$title":"主页","$screen_name":"cn.sensorsdata.demo.HomePage"}};
sensorsApiCloudSdk.trackViewScreen(argument);
上一个
集成文档（APICloud）
下一个
用户关联（APICloud）
最近修改: 2024-12-27