SDK API (小程序)
|
收藏
1. SDK 初始化参数
参数 | 类型 | 默认值 | 含义 | 备注 |
---|---|---|---|---|
name | String | sensors | SDK 使用的一个默认的全局变量,会注册在 App 全局函数内,在 Page 中可以通过 app[name].track 来使用 | |
server_url | String | 数据接收地址 |
| |
autoTrack | Object | 无 | 是否开启自动采集 |
|
show_log | Boolean | true | 是否打印 log |
|
send_timeout | Number | 1000 | 请求发送超时时间(如果一个请求发送后,超过规定时间没响应,则继续发送下一条数据) |
|
use_client_time | Boolean | false | 是否使用客户端时间 |
|
max_string_length | Number | 300 | 通用字符串最大长度,超过部分会被截取丢弃(url 太长可能会导致数据发送失败,所以限制长度) | |
allow_amend_share_path | Boolean | true | 设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性,新增一些参数包括当前用户的 Distinct ID 等 |
|
batch_send | Boolean | true | 小程序中是否使用批量发送数据功能 |
|
datasend_timeout | Number | 3000 | 请求发送取消时间 |
|
source_channel | Array | 无 | 需要解析的渠道参数 |
|
is_persistent_save | Object | 无 | 是否需要将最近一次渠道信息保存到 wxStorage 中 |
|
preset_properties | Object | 无 | 配置采集指定预置属性 |
|
autotrack_exclude_page | Object | 无 | 配置指定页面不采集 $MPViewScreen 页面浏览事件 |
|
framework | Object | 无 | 如果使用 Taro 框架开发小程序,元素点击事件会触发多次,配置 Taro 参数之后可以只采集一次 |
|
preset_events | Object | 无 | 预置事件的自定义控制 |
|
2. 全埋点采集逻辑
事件名称 | 生命周期 | 采集时机 | 说明 |
---|---|---|---|
$MPLaunch(小程序启动) | App.onLaunch | 小程序进程被杀死,重新打开时会触发 |
|
$MPShow(小程序显示) | App.onShow | 小程序启动,或从后台进入前台显示 |
|
$MPHide(小程序进入后台) | App.onHide | 点击小程序右上角退出按钮、微信进入后台、手机锁屏、小程序进程被杀死时 |
|
$MPViewScreen(小程序页面浏览) | Page.onShow | 小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时触发 |
|
$MPShare(小程序分享) | Page.onShareAppMessage | 设置这个函数后,点击分享按钮触发 |
|
$MPClick(小程序元素点击) | 当 Page 中定义的事件处理函数被触发时采集 |
| |
$MPAddFavorites(小程序收藏) | page.onAddToFavorites | 点击小程序收藏按钮时触发 |
|
$MPPageLeave(小程序页面离开) | page.onHide 或 page.onUnload | 小程序页面隐藏或卸载时触发 |
|
3. 设置事件公共属性
3.1. 设置事件静态公共属性
所有小程序 SDK 支持通过 registerApp 接口设置所有事件都有的公共属性。可以在 app.js 文件引入 sensorsdata.min.js 文件之后,init 方法调用之前使用 registerApp 方法设置公共属性。
// 注册事件公共属性。
var sensors = require('/dist/wechat/sensorsdata.cjs.js');
sensors.setPara({
name: 'sensors',
server_url: '数据接收地址'
});
sensors.registerApp({
userLever: 'VIP3',
userSex: '男'
});
sensors.init();
3.2. 设置事件动态公共属性
版本要求
微信小程序 SDK 1.13.27、支付宝小程序 SDK 1.1.3 及以上版本,其他小程序 SDK 暂不支持。
当设置动态公共属性的时候,注意使用函数类型作为属性值,函数的返回值应当是神策支持的类型,请参考数据格式,否则会被过滤掉。
var i=0
sensors.registerApp({
index: function() {
return ++i; // 返回数字
},
istrue: function() {
return i<10 ? true : false; // 返回bool
},
isEmptyString: function() {
return ""; // 返回字符串
},
isDate: function() {
return new Date('December 17, 1995 03:24:00'); // 返回日期类型
},
isArrayOfStr: function() {
return ["1","2","3"] // 返回元素是字符串的数组
}
})
另外如果函数在异步回调中返回值,这种情况也是会被过滤掉。
sensors.registerApp({
num:function(){
setTimeout(()=>{
return 100
},500)
}
})
需要在 App 实例化之前调用 registerApp() 方法完成公共属性的注册,否则会导致部分数据采集不到注册的公共属性
4. 属性插件化
版本要求
mini 库小程序版本需 0.12.0 及以上版本
属性插件化用于修改埋点事件属性的高级功能,用户可通过属性插件化功能实现对指定事件(或所有事件)的属性进行新增、修改和删除。
4.1. 接口介绍
SDK 提供了 registerPropertyPlugin 方法,通过该方法传入自定义的属性插件对象给指定的事件添加、修改或删除属性。
自定义属性插件对象介绍:
方法名 | 描述 | 示例 |
---|---|---|
properties(data) | 用于对属性进行修改,data 为发送前的完整数据。 data 包括 SDK 采集的所有数据类型: profile_set、 profile_set_once、 track、 track_signup。 可配置该方法中对待发送数据 data 进行属性的添加、删除、修改操作。 |
JS
|
isMatchedWithFilter(data) | 用于对数据进行筛选,data 为发送前的完整数据。 同上面 data 包括所有数据类型。 如果配置了该方法,仅当该方法返回 true 时,配置的 properties 方法才会得到执行。 如果不配置该方法,则配置的 properties 方法始终执行。 |
JS
|
4.2. 使用示例
常用方法:修改事件名为 $MPViewScreen 下的 $url 属性
sensors.registerPropertyPlugin({ isMatchedWithFilter:function(data){ return data.event === "$MPViewScreen"; } properties:function(data){ data.properties['$url'] = 'http://xxx'; } });
JS常用方法:删除所有事件中的 platform 属性
sensors.registerPropertyPlugin({ isMatchedWithFilter:function(data){ return data.type === 'track'; } properties:function(data){ delete data.properties['platform']; } });
JS注意:需要先做事件筛选,再做属性修改。因为 profile 等类型的数据也是可以被修改的。
sensors.registerPropertyPlugin({ isMatchedWithFilter:function(data){ return data.type.slice(0, 7) === 'profile'; } properties:function(data){ delete data.properties['aaa'] = 'bbb'; } });
JS对所有类型数据,修改属性值。注意:这种用法一般情况下是错误的,会导致所有数据(包括 profile 等)都被修改,引发意想不到的情况
sensors.registerPropertyPlugin({ properties:function(data){ data.properties['aaa'] = 'bbb'; } });
JS直接在 properties 里进行筛选和属性修改也是可以的
sensors.registerPropertyPlugin({ properties:function(data){ if(data.event === '$MPViewScreen'){ data.properties['$url'] = 'http://xxxx'; } } });
JS
5. 用户属性设置
5.1. 保留初次属性
对于需要保证只有首次设置时有效的属性,如用户首次充值金额、首次设置的昵称等,可以使用 setOnceProfile 接口进行记录。与 setProfile 方法不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。
// 设置用户属性 subscribers 为 7277
sensors.setOnceProfile({
email:'xxx@xx',
favoriteFruits: ['苹果', '油桃'],
subscribers: 7277
});
// 再次设置用户属性 subscribers 为 7278 不生效,属性值仍然是 7277
sensors.setOnceProfile({
subscribers: 7278
});
5.2. 数值属性累加
针对一些数值型属性,如消费总额、用户积分等属性,我们可以使用 incrementProfile 对原值进行累加,神策会自动计算并保存累加之后的值。
// 设置用户订阅次数属性
sensors.incrementProfile({
subscribers: 5
});
// 对用户订阅次数进行累加,此时在神策系统中查询 subscribers 属性值为 10
sensors.incrementProfile({
subscribers: 5
});
5.3. 列表属性追加
对于列表类型用户属性,如用户喜爱的水果、用户爱看的电影等属性,可以调用 appendProfile 接口进行追加一些新值。
// 设置用户喜爱的水果属性
sensors.appendProfile({
favoriteFruits: ['葡萄', '香蕉']
});
// 对用户喜爱的水果属性追加新值
sensors.appendProfile({
favoriteFruits: ['苹果', '桃子']
});
6. 自定义匿名 ID
默认情况下,SDK 会生成匿名 ID 并可以保证该 ID 的唯一性,如果需要替换神策默认分配的匿名 ID ,可以在配置初始化 SDK 参数之后(init 接口调用之前)立即调用 identify 方法进行替换。
// 自定义匿名 ID
sensors.identify('自定义匿名 ID', true);
7. 关联登录 ID
小程序中触发的事件默认由 SDK 生成的 UUID 标识用户,开发者可以调用 login 接口,传入业务 ID,与匿名 ID 关联。
// 关联登录 ID
sensors.login('登录 ID');
8. 获取预置属性
某些情况下可能需要在前端获取 SDK 预置属性,SDK 支持使用 getPresetProperties 方法获取部分事件预置属性。
// 获取事件预置属性
sensors.getPresetProperties();
- 此接口只有微信小程序 SDK 支持
9. 切换回匿名 ID
SDK 提供 logout 接口切换回调用 login 接口之前的匿名 ID。
// 切换回匿名 ID
sensors.logout();
10. 清除公共属性
对于调用 registerApp 设置的公共属性,SDK 提供 clearAppRegister 接口清除这些属性。
// 清除设置的 current_url 和 referrer 公共属性
sensors.clearAppRegister(['current_url', 'referrer']);
11. 设置匿名 ID 为 OpenID
微信小程序 SDK 提供了 bindOpenid 接口将匿名 ID 设置为 OpenID。
wx.request({
url: '获取 OpenID 的后端接口',
success: function(res){
sensors.bindOpenid(res.openid);
},
complete: function(){
sensors.init();
}
});
- 此接口只有满足下面两个条件才能支持!不满足下面条件的可以使用 identify('openid', true) 接口;
- bindOpenid 仅在 ID-Mapping 3.0 支持,使用前请确认 SA 后端是否支持 ID-Mapping 3.0;
- bindOpenid 微信小程序 SDK 需要在 v1.18.3 版本上才支持!
12. 获取匿名 ID
小程序 SDK 提供了 getAnonymousID 接口来获取匿名 ID。
sensors.getAnonymousID();
13. 采集小程序页面浏览时长
小程序 SDK 可以通过开启 $MPPageLeave 预置事件来自动采集。
- 1.14.20 及以上版本的微信小程序 SDK 支持
- 1.1.7 及以上版本的支付宝小程序 SDK 支持
sensors.setPara({
autoTrack: {
pageLeave: true // 默认不开启,为 false
}
});
// $MPPageLeave 预置事件中会采集 event_duration 预置属性来记录页面浏览时长,单位为秒
14. 本地存储加密功能
目前 SDK 保存在 storage 中的信息包含用户信息及 register 设置的属性信息,可以对 storage 中的数据进行深层加密,保证安全性
版本要求
- 微信小程序 SDK 1.14.9 及以上版本
14.1. 功能配置
// app.js
var sensors = require('/dist/wechat/sensorsdata.cjs.js');
sensors.setPara({
name: 'sensors',
server_url: '数据接收地址',
encrypt_storage : true // 是否开启本地加密存储
});
15. 埋点数据的加密功能
为了加强埋点数据的安全性,神策分析支持对埋点数据进行加密,并以密文的形式对数据进行存储和发送。
- 本功能需要服务端的配合,可以联系神策客户成功/项目经理协助开通服务端解密功能。
- 加密插件下线时注意事项:
- 主 SDK 版本回退至 SDK 版本号 >= 1.14.27 版本时 ,只下线加密插件。
- 主 SDK 版本要回退到 1.14.27 以下版本时,下线加密插件,需要修改配置 storage_prepare_data_key
sensors.setPara({
storage_prepare_data_key:''//本地存储 key 值,字符串格式
})
- 开启加密后,如果服务端不支持解密,数据无法入库,会丢失,埋点管理中不会有报错
版本要求
- 微信小程序 SDK v.14.27 及以上版本
- Edge v0.3.0及以上的版本
- SDF 2.3及以上的版本
15.1. SDK 端开启加密
参考插件 encryption 埋点数据加密
16. 支持动态禁用/启用 API
// 禁用 API 执行
sensors.disableSDK()
// 恢复 API 执行
sensors.enableSDK()
注意:必须在 init 后调用,详细参考 disableSDK
- 此接口只有微信小程序 SDK 支持
17. 对发送的数据进行自定义加密
如果需要对发送的数据进行国密等格式的自定义加密,可以使用 自定义加密插件
- 此接口只有微信小程序 SDK 支持
注:本文档内容为神策产品使用和技术细节说明文档,不包含适销类条款;具体企业采购产品和技术服务内容,以商业采购合同为准。