菜单

基础 API 介绍（微信小程序）

 

SDK 初始化参数

参数 类型 默认值 含义 备注
name String sensors SDK 使用的一个默认的全局变量，会注册在 App 全局函数内，在 Page 中可以通过 getApp[name].track 来使用  
server_url String 数据接收地址  
  • 请在微信公众平台 > 开发 > 开发设置 > 服务器域名中，把这个地址添加上。
autoTrack Object 无 是否开启自动采集
  • 六个属性参数（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_log Boolean true 是否打印 log
  • 设置 true 后会在模拟器控制台打 log，会显示发送的数据，设置 false 表示不显示。
send_timeout Number 1000 请求发送超时时间（如果一个请求发送后，超过规定时间没响应，则继续发送下一条数据）
  • 单位为毫秒；
  • 支付宝小程序 SDK 支持。
use_client_time Boolean false 是否使用客户端时间
  • 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false，表示不使用客户端时间，使用服务端时间，如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()}，注意这里必须是 Date 类型，那么这条数据就会使用你在属性中传入的这个时间；
  • 从 1.14.6 版本开始 SDK 默认使用客户端时间发送数据，不再支持此配置；
max_string_length Number 5000 通用字符串最大长度，超过部分会被截取丢弃  
allow_amend_share_path Boolean true 设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性，新增一些参数包括当前用户的 Distinct ID 等
  • 如果要自动采集分享信息，必须设置为 true，默认为 true；
  • 仅微信小程序 SDK 支持。
batch_send Boolean true 小程序中是否使用批量发送数据功能
  • 微信小程序 SDK 1.14.11 及以上版本默认开启；
datasend_timeout Number 3000 请求发送取消时间
  • 单位为毫秒，请求发送后，在规定时间内未返回结果，则取消请求；
  • 1.12.9 及以上版本支持；
source_channel Array 无 需要解析的渠道参数
  • 默认情况下，只会解析参数 utm_source、utm_content、utm_campaign、utm_medium、utm_term 设置到预置事件中，可以通过配置该参数来解析其他自定义参数，例如 ['channel_code']，_channel_code 属性会作为预置事件的预置属性，_latest_channel_code 会作为所有事件的公共属性上报；
  • 1.13.8 及以上版本支持；
is_persistent_save Object 无 是否需要将最近一次渠道信息保存到 Storage 中
  • 1.13.9 及以上版本支持；
  • 两个属性参数（utm、share），默认是 false；

preset_properties

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

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

 

全埋点采集逻辑

事件名称 生命周期 采集时机 说明
$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 小程序页面隐藏或卸载时触发  

设置事件公共属性

设置事件静态公共属性

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

// 注册事件公共属性。 var sensors = require('/dist/wechat/sensorsdata.cjs.js'); sensors.registerApp({	userLever: 'VIP3',	userSex: '男' }); sensors.init();

设置事件动态公共属性

版本要求

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

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

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

用户属性设置

保留初次属性

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

// 设置用户属性 subscribers 为 7277 sensors.setOnceProfile({	email:'xxx@xx',	favoriteFruits: ['苹果', '油桃'],	subscribers: 7277 }); // 再次设置用户属性 subscribers 为 7278 不生效，属性值仍然是 7277 sensors.setOnceProfile({ subscribers: 7278 });

数值属性累加

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

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

列表属性追加

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

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

自定义匿名 ID

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

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

获取预置属性

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

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

清除公共属性

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

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

获取匿名 ID

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

sensors.getAnonymousID();

采集小程序页面浏览时长

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

  1. 1.14.20 及以上版本的微信小程序 SDK 支持
sensors.init({	autoTrack: {	pageLeave: true // 默认不开启，为 false	} }); // $MPPageLeave 预置事件中会采集 event_duration 预置属性来记录页面浏览时长，单位为秒

批量发送

在初始化中可以配置 batch_send 进行批量发送。

sensors.init({ batch_send:{ send_timeout: 6000, // 默认间隔 6000 毫秒就轮询发一次数据 max_length: 6 // 默认超过 6 条数据，就进行批量发送 } });

本地存储加密

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

版本要求

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

功能配置

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