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、$MPShare(0.9以上版本的 SDK 支持),其中 $MPShare 事件 1.9 版本以上支持,$MPPageLeave 事件 1.14.20 版本以上支持,$MPClick、$MPPageLeave 事件默认不采集,详细介绍见预置事件
  • 微信、支付宝、百度小程序 SDK 支持。
show_logBooleantrue是否打印 log
  • 设置 true 后会在模拟器控制台打 log,会显示发送的数据,设置 false 表示不显示。
send_timeoutNumber1000请求发送超时时间(如果一个请求发送后,超过规定时间没响应,则继续发送下一条数据)
  • 单位为毫秒;
  • 支付宝小程序 SDK 支持。
use_client_timeBooleanfalse是否使用客户端时间
  • 因为客户端系统时间的不准确,会导致发生这个事件的时间有误,所以这里默认为 false ,表示不使用客户端时间,使用服务端时间,如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ,注意这里必须是 Date 类型,那么这条数据就会使用你在属性中传入的这个时间;
  • 从 1.14.6 版本开始 SDK 默认使用客户端时间发送数据,不再支持此配置;
  • 仅微信小程序 SDK 支持。
max_string_lengthNumber300通用字符串最大长度,超过部分会被截取丢弃(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 设置到预置事件中,可以通过配置该参数来解析其他自定义参数,例如['channel_code'],_channel_code 属性会作为预置事件的预置属性,_latest_channel_code 会作为所有事件的公共属性上报
  • 1.13.8 及以上版本支持;
  • 微信、百度、字节跳动、QQ 小程序 SDK 支持。
is_persistent_saveObject是否需要将最近一次渠道信息保存到 wxStorage
  • 1.13.9 及以上版本支持;
  • 两个属性参数( utm、 share),默认是 false;
  • 仅微信小程序 SDK 支持;

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 及以上版本支持;
  • 仅微信小程序 SDK 支持。
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小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时触发
  • 每次打开页面都会调用一次;
  • 微信、支付宝、百度小程序 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('/dist/wechat/sensorsdata.cjs.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. 属性插件化

版本要求

mini 库小程序版本需 0.12.0 及以上版本

属性插件化用于修改埋点事件属性的高级功能,用户可通过属性插件化功能实现对指定事件(或所有事件)的属性进行新增、修改和删除。

4.1. 接口介绍

SDK 提供了 registerPropertyPlugin 方法,通过该方法传入自定义的属性插件对象给指定的事件添加、修改或删除属性。

自定义属性插件对象介绍:

方法名描述示例
properties(data)

用于对属性进行修改,data 为发送前的完整数据。

data 包括 SDK 采集的所有数据类型:

profile_set、

profile_set_once、

track、

track_signup。


可配置该方法中对待发送数据 data 进行属性的添加、删除、修改操作。

{
	properties:function(data){
	  // 添加
	  // data.properties.hello = 'world'
	  
	  // 修改
	  // data.properties.$title = 'new title'
	  
	  // 删除
	  // delete data.properties.$screen_width		
	}
}
JS
isMatchedWithFilter(data)

用于对数据进行筛选,data 为发送前的完整数据。

同上面 data 包括所有数据类型。


如果配置了该方法,仅当该方法返回 true 时,配置的 properties 方法才会得到执行。


如果不配置该方法,则配置的 properties 方法始终执行。

{
	isMatchedWithFilter:function(data){
		// 筛选事件名为 $SignUp 的事件
		if(data.event === '$SignUp'){
			return true;
		}

		// 筛选在页面标题为 home 的事件
		if(data.properties.$title === 'home'){
			return true;
		}
		
		// 其他事件不会执行 properties 方法
		return false;
	}
}
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
});

JS

5.2. 数值属性累加

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

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

5.3. 列表属性追加

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

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

6. 自定义匿名 ID

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

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

7. 关联登录 ID

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

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

8. 获取预置属性

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

// 获取事件预置属性
sensors.getPresetProperties();
JS
  • 此接口只有微信小程序 SDK 支持

9. 切换回匿名 ID

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

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

10. 清除公共属性

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

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

11. 设置匿名 ID 为 OpenID

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

wx.request({
	url: '获取 OpenID 的后端接口',
	success: function(res){
		sensors.bindOpenid(res.openid);
	},
	complete: function(){
		sensors.init();
	}
});
JS
  • 此接口只有满足下面两个条件才能支持!不满足下面条件的可以使用  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();
JS

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

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

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

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

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 // 是否开启本地加密存储
});
JS

15. 埋点数据的加密功能

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

  • 本功能需要服务端的配合,可以联系神策客户成功/项目经理协助开通服务端解密功能。
  • 加密插件下线时注意事项:
    • 主 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及以上的版本

15.1. SDK 端开启加密

参考插件 encryption 埋点数据加密

16. 支持动态禁用/启用 API

// 禁用 API 执行
sensors.disableSDK()
// 恢复 API 执行
sensors.enableSDK()
CODE

注意:必须在 init 后调用,详细参考 disableSDK 

  • 此接口只有微信小程序 SDK 支持

17. 对发送的数据进行自定义加密

如果需要对发送的数据进行国密等格式的自定义加密,可以使用 自定义加密插件

  • 此接口只有微信小程序 SDK 支持