1. SDK 的集成和初始化

1.1. 集成 SDK

  • GitHub 上获取微信小程序源码
  • 将 sensorsdata.min.js 文件放入小程序项目中
  • 在 app.js 文件中通过 require() 引入 SDK
var sa = require('./utils/sensorsdata.min.js');
JAVASCRIPT
  • 通过 npm i sa-sdk-miniprogram 安装 SDK
  • 在 main.js 中通过 import 引入 SDK
import sa from 'sa-sdk-miniprogram'
JAVASCRIPT
  • 通过 npm i sa-sdk-miniprogram 安装 SDK
  • 在 app.jsx 中通过 import 引入 SDK
import sa from 'sa-sdk-miniprogram'
JAVASCRIPT
  • 通过 npm i sa-sdk-miniprogram 安装 SDK
  • 在 main.js 中通过 import 引入 SDK,注意需要在 vue 之前引入
import sa from 'sa-sdk-miniprogram'
JAVASCRIPT
  • 通过 npm i sa-sdk-miniprogram 安装 SDK
  • 在 app.wpy 中通过 import 引入 SDK
import sa from 'sa-sdk-miniprogram'
JAVASCRIPT


  • 微信小程序 SDK 压缩文件 sensorsdata.min.js 大小约为 28 kb
  • 需要在 App 实例化之前调用 setPara() 和 init(),否则可能会造成部分预置事件丢失

1.2. 配置初始化参数

引入 SDK 后,可通过 setPara() 可进行 SDK 初始化参数配置

sa.setPara({
	name: 'sensors',
	server_url: '您的数据接收地址',
	// 全埋点控制开关
	autoTrack: false,
	// 自定义渠道追踪参数,如source_channel: ["custom_param"]
	source_channel: [],
	// 是否允许控制台打印查看埋点数据(建议开启查看)
	show_log: true,
	// 是否允许修改onShareAppMessage里return的path,用来增加(用户id,分享层级,当前的path),在app onShow中自动获取这些参数来查看具体分享来源,层级等
	allow_amend_share_path: true
});
JS

1.3. 初始化 SDK

setPara() 配置初始化参数后,可调用 init() 方法来初始化 SDK

// 初始化 SDK
sa.init();
JS

在调用 init() 接口之前,采集的数据被缓存在内存中;调用 init() 接口后,会将缓存的数据通过网络发送出去

2. SDK 基本配置

2.1. 配置全埋点

$MPLaunch、$MPShow 、$MPHide、$MPViewScreen 、$MPShare 需要  0.9 及以上版本 SDK

$MPClick 需要 1.13.18 及以上版本 SDK

setPara() 函数中 autoTrack 可用于配置需要开启的全埋点类型

sa.setPara({
	autoTrack:{ 
		appLaunch:true, // true 则开启 $MPLaunch 事件采集,
		appShow:true, // true 则开启 $MPShow 事件采集
		appHide:true, // true 则开启 $MPHide 事件采集
		pageShow:true, // true 则开启 $MPViewScreen 事件采集
		pageShare:true, // true 则开启 $MPShare 事件采集
		mpClick: true // true 则开启 $MPClick 事件采集
	}

	/**
	 * 其他配置
	 */
});
JS

全埋点采集时机,可参考 全埋点采集逻辑

使用框架开发小程序时,如果框架编译后使用 Component 构造器形成页面,$MPViewScreen, $MPShare 事件的自动采集需要使用 1.13.6 及以上版本的 SDK


2.2. 用户登录

当用户注册成功或者登录成功时,需要调用 login() 方法传入用户 ID

sa.login("登录 ID");
JS

对于自动登录的用户,可以在 SDK 前初始化,获取用户 ID 并调用 login() 方法

2.3. 设置事件公共属性

对于所有事件都需要添加的属性,可在初始化 SDK 前,调用 registerApp() 将属性注册为公共属性

sa.registerApp({
	userLever: 'VIP3',
	userSex: '男'
});
JS

2.4. 代码埋点追踪事件

可通过 track() 方法追踪用户行为事件,并为事件添加自定义属性

// 自定义埋点事件
getApp().sensors.track('click',{
	name: '点击'
});

JS

3. 调试查看事件信息

3.1. 事件的触发日志

setPara() 配置初始化参数时,通过 show_log: true 打开 Log 功能后,微信开发者工具 console 会打印采集的数据信息


3.2. 事件的发送情况

事件数据发送成功时,可以在微信开发者工具的 Network 模块中,可以看到 sa 的图片请求

4. SDK 可选配置

4.1. 全埋点采集逻辑

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

4.2. 设置用户属性

setProfile( properties ): 可以设定用户属性,同一个 key 多次设置时,value 值会进行覆盖替换。

sa.setProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
JS
 其他设置用户属性 API

setOnceProfile( properties );

  • 说明:如果不存在同名属性则设置,存在同名属性,同名属性不会重新设置。
  • 参数:
    • properties:object,必填,要给该用户设置的用户属性;
sa.setOnceProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
JS

incrementProfile( properties );

  • 说明:增加或减少一个用户的某个 Numeric 类型的 Profile,如果该用户属性不存在则自动创建。
  • 参数:
    • properties:object,必选。
sa.incrementProfile({
	subscribers: 5
});
JS

appendProfile( properties );

  • 说明:向某个用户的某个数组类型的 Profile 添加一个或者多个值。
  • 参数:
    • properties:object,必选。
sa.appendProfile({ 
	favoriteFruits: ['葡萄', '香蕉'] 
});
JS

4.3. 渠道追踪

用户通过含有 utm 相关参数的路径访问小程序时,预置事件 $MPLaunch、$MPShow、$MPViewScreen 会解析启动路径中的 utm 相关参数作为自身的属性与属性值,并会设置 $latest_utm 相关属性到所有事件中,在小程序的生命周期内有效;

小程序渠道追踪的其他使用,可参考微信小程序渠道追踪 v1.13

5. SDK API

5.1. SDK 初始化参数

参数类型默认值含义备注
namestirngsensorsSDK 使用的一个默认的全局变量,会注册在 App 全局函数内,在 Page 中可以通过 app[name].track 来使用
appidstring如果需要使用 initWithOpenid() 方法来完成初始化,需要在神策后端配置 appid 和 appsecret ,同时在这里指定 appid
server_urlstring数据接收地址
请在微信公众平台---开发---开发设置---服务器域名中,把这个地址添加上。
autoTrackobject是否开启自动采集六个属性参数( appLaunch、 appShow、 appHide、 pageShow、 pageShare、mpClick),其中 mpClick 默认是 false,其他是 true。即默认采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare(0.9以上版本的 SDK 支持),其中 $MPShare 事件 1.9 版本以上支持,$MPClick 事件默认不采集,详细介绍见预置事件。
show_logbooleantrue是否打印 Log设置 true 后会在模拟器控制台打 logger,会显示发送的数据,设置 false 表示不显示
send_timeoutnumber1000请求发送超时时间(如果一个请求发送后,超过规定时间没响应,则继续发送下一条数据)单位为毫秒
use_client_timebooleanfalse是否使用客户端时间因为客户端系统时间的不准确,会导致发生这个事件的时间有误,所以这里默认为 false ,表示不使用客户端时间,使用服务端时间,如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ,注意这里必须是 Date 类型,那么这条数据就会使用你在属性中传入的这个时间。
allow_amend_share_pathbooleantrue设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性,新增一些参数包括当前用户的 distinct_id 等如果要自动采集分享信息,必须设置为 true
batch_sendbooleanfalse小程序中是否使用批量发送数据功能
datasend_timeoutnumber3000请求发送取消时间单位为毫秒,请求发送后,在规定时间内未返回结果,则取消请求;1.12.9 及以上版本支持
source_channelarray需要解析的渠道参数默认情况下,只会解析参数 utm_source、 utm_content、 utm_campaign、 utm_medium、 utm_term 设置到预置事件中,可以通过配置该参数来解析其他自定义参数,例如['from', 'to'] (1.13.8 及以上版本支持) 。
is_persistent_savebooleanfalse是否需要将最近一次渠道信息保存到 wxStorage 中1.13.9 及以上版本支持





init();

  • 说明:用来标识小程序 SDK 初始化完成,数据可以通过网络发送;此方法不调用,采集的数据会被缓存在内存中,不能通过网络发送;

setOpenid();

  • 说明:用来将匿名 ID 修改为 openid;

initWithOpenid();

  • 说明:当客户希望使用 openid 作为匿名 ID,同时不想自己获取 openid 再修改匿名 ID,而是希望神策自动获取 openid,可以使用这个 API.注意事项可以参考常见问题;

5.2. 采集事件数据

track( eventName,[properties] );

  • 说明:采集自定义事件。
  • 参数:
    • eventName:`string`,必填,事件名称;
    • properties:`object`,选填,为该事件设置的事件属性;

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:电商产品,可以追踪用户注册、浏览商品和下订单等事件。

index.js

// 追踪浏览商品事件。 
var app = getApp();
app.sensors.track('ViewProduct', {
	//String 类型
	ProductName: "MacBook Pro", 
	//Number 类型,-9E15 到 9E15 小数点后最多保留 3 位
	ProductPrice: 123.45, 
	//BOOL 类型,true 或 false
	IsAddedToFav, false
	//List 类型,字符串元素的数组,最大元素个数为 500,其中每个元素使用 UTF-8 编码后最大长度 255 字节
	ProductList:["apple","orange"], 
	//DATETIME 类型,可以直接传 new Date() 或者 传 yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss 格式的字符串。
	ViewTime:new Date()
});
JS

login( userID );

  • 说明:用来做用户关联,当传入的参数与当前 distinct_id 不一致时,会触发 $SignUp 预置事件;
  • 参数:
    • userID: string, 必填,用户 ID 或登录 ID 

registerApp( properties );

  • 说明:用来给所有事件设置公共属性,可以在 app.js 文件引入 sensorsdata.min.js 文件之后, init() 方法调用之前使用 registerApp() 方法设置公共属性。
  • 参数:
    • properties:object,必填,为该方法调用后的所有事件设置的公共事件属性;

app.js

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

quick( ['appLaunch'|'appShow'|'appHide'|'getAnonymousID'], [options], [properties]);

  • 说明:通过给定的第一个参数,来分别实现不同的功能;
  • 参数:
    • appLaunch:string, 用来发送一条预置事件 $MPLaunch 数据,一般在小程序 App 实例的 onLaunch 生命周期中调用;
      • 第二个参数 options,必须, 需要传入返回的生命周期函数参数对象;
      • 第三个参数 properties,非必须,可以传入要设置给预置事件 $MPLaunch 事件的自定义属性;
    • appShow:string, 用来发送一条预置事件 $MPShow 数据,一般在小程序 App 实例的 onShow 生命周期中调用;
      • 第二个参数 options,必须, 需要传入返回的生命周期函数参数对象;
      • 第三个参数 properties,非必须,要设置给预置事件 $MPShow 事件的自定义属性
    • appHide:string, 用来发送一条预置事件 $MPHide 数据,一般在小程序 App 实例的 onHide 生命周期中调用;
      • 第二个参数 options,非必须, 要设置给预置事件 $MPHide 事件的自定义属性;
    • getAnonymousID:string, 用来获取匿名 ID;

5.3. 采集用户数据

setProfile( properties );

  • 说明:设置用户的属性,如果存在则覆盖。
  • 参数:
    • properties:object,必填,要给该用户设置的用户属性;

app.js

sa.setProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
JS

setOnceProfile( properties );

  • 说明:如果不存在同名属性则设置,存在同名属性,同名属性不会重新设置。
  • 参数:
    • properties:object,必填,要给该用户设置的用户属性;

app.js

sa.setOnceProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
JS

incrementProfile( properties );

  • 说明:增加或减少一个用户的某个 Numeric 类型的 Profile,如果该用户属性不存在则自动创建。
  • 参数:
    • properties:object,必选。

app.js

sa.incrementProfile({
	subscribers: 5
});
JS

appendProfile( properties );

  • 说明:向某个用户的某个数组类型的 Profile 添加一个或者多个值。
  • 参数:
    • properties:object,必选。

app.js

sa.appendProfile({ 
	favoriteFruits: ['葡萄', '香蕉'] 
});
JS

5.4. 其他 API

identify( 'anonymousID', [boolean]);

  • 说明:用来修改当前小程序访问用户的匿名 ID;
  • 参数:
    • anonymousID: String ,要使用的匿名 ID;
    • boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到微信 storage 中;不填或者设置为 false,表示该匿名 ID 只在小游戏本次生命周期中有效,下次冷启动后使用的仍然时修改之前的匿名 ID;

getPresetProperties();

  • 说明:用来获取部分预置属性;

clearAllRegister();

  • 说明:用来清除存储在 storage 中的公共属性;

logout( [boolean])

  • 说明:用来将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;
  • 参数:
    • boolean: Boolean, 不填, 表示将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;设置为 true,表示将当前的 Distinct ID 切换为一个重新生成的 UUID;