1. SDK 初始化参数

参数类型默认值含义备注
nameStringsensorsSDK 使用的一个默认的全局变量，会注册在 App 全局函数内，在 Page 中可以通过 getApp[name].track 来使用
server_urlString数据接收地址
  • 请在微信公众平台 → 开发 → 开发设置 → 服务器域名中，把这个地址添加上。
autoTrackObject无是否开启自动采集
  • 六个属性参数( appLaunch、 appShow、 appHide、 pageShow、 pageShare、mpClick、pageLeave)，其中 mpClick、 pageLeave 默认是 false，其他是 true。即默认采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare（0.9以上版本的 SDK 支持），其中 $MPShare 事件 1.9 版本以上支持，$MPPageLeave 事件 1.14.20 版本以上支持，$MPClick、$MPPageLeave 事件默认不采集，详细介绍见预置事件；
show_logBooleantrue是否打印 log
  • 设置 true 后会在模拟器控制台打 log，会显示发送的数据,设置 false 表示不显示。
send_timeoutNumber1000请求发送超时时间（如果一个请求发送后，超过规定时间没响应，则继续发送下一条数据）
  • 单位为毫秒；
  • 支付宝小程序 SDK 支持。
use_client_timeBooleanfalse是否使用客户端时间
  • 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端时间，使用服务端时间，如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date 类型，那么这条数据就会使用你在属性中传入的这个时间；
  • 从 1.14.6 版本开始 SDK 默认使用客户端时间发送数据，不再支持此配置；
max_string_lengthNumber500通用字符串最大长度，超过部分会被截取丢弃（url 太长可能会导致数据发送失败，所以限制长度）
allow_amend_share_pathBooleantrue设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性，新增一些参数包括当前用户的 Distinct ID 等
  • 如果要自动采集分享信息，必须设置为 true，默认为 true；
  • 仅微信小程序 SDK 支持。
batch_sendBooleantrue小程序中是否使用批量发送数据功能
  • 微信小程序 SDK 1.14.11 及以上版本默认开启；
datasend_timeoutNumber3000请求发送取消时间
  • 单位为毫秒，请求发送后，在规定时间内未返回结果，则取消请求；
  • 1.12.9 及以上版本支持；
source_channelArray无需要解析的渠道参数
  • 默认情况下，只会解析参数 utm_source、 utm_content、 utm_campaign、 utm_medium、 utm_term 设置到预置事件中，可以通过配置该参数来解析其他自定义参数，例如['channel_code']，_channel_code 属性会作为预置事件的预置属性，_latest_channel_code 会作为所有事件的公共属性上报；
  • 1.13.8 及以上版本支持；
is_persistent_saveObject无是否需要将最近一次渠道信息保存到 Storage 中
  • 1.13.9 及以上版本支持；
  • 两个属性参数( utm、 share)，默认是 false；

preset_properties

Object无配置采集指定预置属性
  • 属性参数（ url_path）；
  • 微信小程序 SDK 支持配置采集 url_path 属性；
autotrack_exclude_pageObject无配置指定页面不采集 $MPViewScreen 页面浏览事件 
  • 一个参数（pageShow）；
  • 例如 : autotrack_exclude_page: { pageShow: ['pages/index/index'] }，这样设置之后，SDK 不会采集页面路径为 'pages/index/index' 页面的 $MPViewScreen 事件，1.14.2 及以上版本支持；
frameworkObject无

如果使用 Taro 框架开发小程序，元素点击事件会触发多次，配置 Taro 参数之后可以只采集一次

  • 一个属性参数（taro）；
  • 可配置为 framework: {taro: Taro}。
preset_eventsObject无预置事件的自定义控制
  • 两个属性参数（moments_page, collect_element）,1.14.12 及以上版本支持；
  • moments_page 支持控制是否开启朋友圈单页面数据采集，默认 false， 配置 true 单页面可以发送数据；
  • collect_element 用户点击元素时会触发这个函数，并返回点击事件信息，用来判断是否要采集当前这个元素，返回真表示采集，返回假表示不采集;
  • 仅微信小程序 SDK 支持。


2. 全埋点采集逻辑

事件名称生命周期采集时机说明
$MPLaunch（小程序启动）App.onLaunch小程序进程被杀死，重新打开时会触发
  • 小程序初始化完成时，全局只触发一次；
$MPShow（小程序显示）App.onShow小程序启动，或从后台进入前台显示
  • 启动小程序时，后台进入前台；
$MPHide（小程序进入后台）App.onHide点击小程序右上角退出按钮、微信进入后台、手机锁屏、小程序进程被杀死时
  • 小程序从前台进入后台；
$MPViewScreen（小程序页面浏览）Page.onShow小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时触发
  • 每次打开页面都会调用一次；
$MPShare（小程序分享）Page.onShareAppMessage设置这个函数后，点击分享按钮触发
  • 暂时只能获取到用户触发分享，无法监听是否分享成功的反馈；
$MPClick（小程序元素点击）
当 Page 中定义的事件处理函数被触发时采集
  • 目前只支持 tap/ longtap / longpress 三类事件；
$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.registerApp({
	userLever: 'VIP3',
	userSex: '男'
}); 
sensors.init();
JS

3.2. 设置事件动态公共属性

版本要求

微信小程序 SDK > v1.13.27

当设置动态公共属性的时候，注意使用函数类型作为属性值，函数的返回值应当是神策支持的类型，请参考数据格式，否则会被过滤掉。

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"] // 返回元素是字符串的数组
  }
})
JS

另外如果函数在异步回调中返回值，这种情况也是会被过滤掉。

sensors.registerApp({
    num:function(){
        setTimeout(()=>{
            return 100
        },500)
    }
})
JS

4. 用户属性设置

4.1. 保留初次属性

对于需要保证只有首次设置时有效的属性，如用户首次充值金额、首次设置的昵称等，可以使用 setOnceProfile 接口进行记录。与 setProfile 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。

// 设置用户属性 subscribers 为 7277
sensors.setOnceProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});

// 再次设置用户属性 subscribers 为 7278 不生效，属性值仍然是 7277
sensors.setOnceProfile({
    subscribers: 7278
});
JS

4.2. 数值属性累加

针对一些数值型属性，如消费总额、用户积分等属性，我们可以使用 incrementProfile 对原值进行累加，神策会自动计算并保存累加之后的值。

// 设置用户订阅次数属性
sensors.incrementProfile({
	subscribers: 5
});
// 对用户订阅次数进行累加，此时在神策系统中查询 subscribers 属性值为 10
sensors.incrementProfile({
	subscribers: 5
});
JS

4.3. 列表属性追加

对于列表类型用户属性，如用户喜爱的水果、用户爱看的电影等属性，可以调用 appendProfile 接口进行追加一些新值。

// 设置用户喜爱的水果属性
sensors.appendProfile({ 
	favoriteFruits: ['葡萄', '香蕉'] 
});
// 对用户喜爱的水果属性追加新值
sensors.appendProfile({ 
	favoriteFruits: ['苹果', '桃子'] 
});
JS

5. 自定义匿名 ID

默认情况下，SDK 会生成匿名 ID 并可以保证该 ID 的唯一性，如果需要替换神策默认分配的匿名 ID ，可以在配置初始化 SDK 参数之后（init 接口调用之前）立即调用 identify 方法进行替换。

// 自定义匿名 ID
sensors.identify('自定义匿名 ID', true);
JS

6. 获取预置属性

某些情况下可能需要在前端获取 SDK 预置属性，SDK 支持使用 getPresetProperties 方法获取部分事件预置属性。

// 获取事件预置属性
sensors.getPresetProperties();
JS

7. 清除公共属性

对于调用 registerApp 设置的公共属性，SDK 提供 clearAppRegister 接口清除这些属性。

// 清除设置的 current_url 和 referrer 公共属性
sensors.clearAppRegister(['current_url', 'referrer']);
JS

8. 获取匿名 ID 

小程序 SDK 提供了 getAnonymousID 接口来获取匿名 ID。

sensors.getAnonymousID();
JS

9. 采集小程序页面浏览时长

小程序 SDK 可以通过开启 $MPPageLeave 预置事件来自动采集。

  1. 1.14.20 及以上版本的微信小程序 SDK  支持
sensors.init({
	autoTrack: {
		pageLeave: true // 默认不开启，为 false
	}
});

// $MPPageLeave 预置事件中会采集 event_duration 预置属性来记录页面浏览时长，单位为秒
JS

10. 本地存储加密功能

目前 SDK 保存在 storage 中的信息包含用户信息及 register 设置的属性信息，可以对 storage 中的数据进行深层加密，保证安全性

版本要求

  • 微信小程序 SDK 1.14.9  及以上版本 

10.1. 功能配置

  // app.js
var sensors = require('/dist/wechat/sensorsdata.cjs.js');
sensors.init({
	name: 'sensors',
	server_url: '数据接收地址',
	encrypt_storage : true // 是否开启本地加密存储
});
JS