1. SDK 初始化参数

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

preset_properties

Object配置采集指定预置属性
  • 两个属性参数(location, url_path);
  • 微信小程序 SDK 中 location 可配置参数值:{ type:  'wgs84' } 或者 { type:  'gcj02' },preset_properties: { location: { type:  'wgs84' }}
  • 支付宝小程序 SDK 可配置的参数值为 true 或者 false,如 preset_properties: { location: true }
  • 配置 location 属性后,所有事件都会采集纬度属性:$latitude、经度属性:$longitude; 配置 url_path 属性后,所有事件都会采集 $url_path 属性;
  • 微信、支付宝小程序 SDK 支持配置采集经纬度属性。微信小程序 SDK 支持配置采集 url_path 属性;
  • 如果想采集用户的经纬度属性,必须由开发者引导用户完成授权;
autotrack_exclude_pageObject配置指定页面不采集 $MPViewScreen 页面浏览事件 
  • 一个参数(pageShow);
  • 例如 : autotrack_exclude_page: { pageShow: ['pages/index/index'] },这样设置之后,SDK 不会采集页面路径为 'pages/index/index' 页面的 $MPViewScreen 事件;

  • 仅微信小程序 SDK 支持。
frameworkObject

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

  • 一个属性参数(taro);
  • 可配置为 framework: {taro: Taro}
  • 如果 Taro 版本是 2.x 或 3.0.19 以上版本不需要配置此参数;
  • 仅微信、支付宝小程序 SDK 支持。
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小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时触发
  • 每次打开页面都会调用一次;
  • 微信、支付宝、百度小程序 SDK 支持;
$MPShare(小程序分享)Page.onShareAppMessage设置这个函数后,点击分享按钮触发
  • 暂时只能获取到用户触发分享,无法监听是否分享成功的反馈;
  • 仅微信小程序 SDK 支持;
$MPClick(小程序元素点击)
当 Page 中定义的事件处理函数被触发时采集
  • 目前只支持 tap/ longtap / longpress 三类事件;
  • 微信、支付宝、百度小程序 SDK 支持;
$MPAddFavorites(小程序收藏)page.onAddToFavorites点击小程序收藏按钮时触发
  • 仅微信小程序 SDK 支持;
$MPPageLeave(小程序离开)page.onHide 或 page.onUnload小程序页面隐藏或卸载时触发
  • 仅微信小程序 SDK 支持;

3. 设置事件公共属性

3.1. 设置事件静态公共属性

所有小程序 SDK 支持通过 registerApp 接口设置所有事件都有的公共属性。可以在 app.js 文件引入 sensorsdata.min.js 文件之后,init 方法调用之前使用 registerApp 方法设置公共属性。

// 注册事件公共属性。 
var sensors = require('sensorsdata.min.js');
sensors.setPara({
	name: 'sensors',
	server_url: '数据接收地址'
});
sensors.registerApp({
	userLever: 'VIP3',
	userSex: '男'
}); 
sensors.init();
JS

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

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

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

需要在 App 实例化之前调用 registerApp() 方法完成公共属性的注册,否则会导致部分数据采集不到注册的公共属性

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. 关联登录 ID

小程序中触发的事件默认由 SDK 生成的 UUID 标识用户,开发者可以调用 login 接口,传入业务 ID,与匿名 ID 关联。

// 关联登录 ID
sensors.login('登录 ID');
JS

7. 获取预置属性

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

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

8. 切换回匿名 ID

SDK 提供 logout 接口切换回调用 login 接口之前的匿名 ID。

// 切换回匿名 ID
sensors.logout();
JS

9. 清除公共属性

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

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

10. 设置匿名 ID 为 OpenID

微信小程序 SDK 提供了 setOpenid 接口将匿名 ID 设置为 OpenID。

wx.request({
	url: '获取 OpenID 的后端接口',
	success: function(res){
		sensors.setOpenid(res.openid);
	},
	complete: function(){
		sensors.init();
	}
});
JS
  • 此接口只有微信小程序 SDK 支持,其他小程序 SDK 可以使用 identify('', true) 接口;
  • setOpenid 接口需在 init 之前调用
  • 由于获取 OpenID 需要通过网络从服务端返回,会存在获取失败的情况。获取失败后,由于没有执行 init 方法,用户触发的数据会被保存到内存中,当小程序生命周期结束后,这些数据就会丢失;

11. 获取匿名 ID 

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

sensors.getAnonymousID();
JS

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

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

  1. 目前仅 1.14.20 及以上版本的微信小程序 SDK  支持,其他小程序 SDK 不支持
  2. 不支持对 $MPPageLeave 预置事件添加自定义属性
sensors.setPara({
	autoTrack: {
		pageLeave: true 
	}
});

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

13. 埋点数据的加密功能

为了加强埋点数据的安全性,神策分析支持对埋点数据进行加密,并以密文的形式对数据进行存储和发送。

  • 本功能需要服务端的配合,可以联系神策客户成功/项目经理协助开通服务端解密功能。
  • 加密插件下线时注意事项:
    • 主 SDK 版本回退至 SDK 版本号 >= 1.14.27 版本时 ,只下线加密插件。
    • 主 SDK 版本要回退到 1.14.27 以下版本时,下线加密插件,需要修改配置 storage_prepare_data_key
sensors.setPara({
   storage_prepare_data_key:''//本地存储 key 值,字符串格式
})
JS
  • 开启加密后,如果服务端不支持解密,数据无法入库,会丢失,埋点管理中不会有报错

版本要求

  • 微信小程序 SDK v.14.27 及以上版本
  • Edge v0.3.0及以上的版本
  • SDF 2.3及以上的版本

13.1. SDK 端开启加密

使用加密插件 aes.cmd.min.js aes.esm.min.js  ,必须先集成和初始化微信小程序 SDK,代码示例如下:

// app.js 
import sensors from './utils/sensorsdata.min.js';
import AesEncryption from './utils/aes.esm.min.js';
 
或者
var AesEncryption = require('./utils/aes.cmd.js');
 
注意别用错了 esm  与 cmd
 
// 微信小程序 SDK 初始化参数配置
sensors.setPara({
  server_url: '数据接收地址',
})
 
// 加密插件集成
sensors.usePlugin(AesEncryption,{
      k:'加密密钥',
      kid: 1, // 密钥编号
      khash: '密钥哈希值'
  })
 
// 完成小程序 SDK 的初始化
sensors.init();
JS

13.2. 加密插件参数说明

参数名参数值类型参数说明
kstring加密密钥
kidnumber密钥编号
khashstring密钥哈希值