在使用前,请先阅读数据模型的介绍。
如想查看 SDK 历史版本,请参考 SDK 更新日志

1. 获取和引入神策分析 SDK

1.1. 安装方法

1.1.1. 下载文件

从 GitHub 上下载微信小程序 SDKsensorsdata.min.js

目前微信小程序 SDK 压缩文件 sensorsdata.min.js 大小约为 28kb。

1.1.2. 引入 SDK 、配置参数并且完成初始化

把文件放在小程序项目中,然后在 app.js 中通过 require() 引入文件 ; 调用 setPara() 方法设置初始化参数(必须在 require() 之后,立即调用 setPara() 方法设置);如果异步的获取 openid 等操作已经完成,此时调用 init() 方法标志已完成初始化;
注意:init() 方法必须调用,否则不会发数据。

小程序 app.js 的顶部引入如下代码

app.js

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

1.2. setPara( args ) 方法

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

2. 如何标识用户

如何准确的标识用户

在进行任何埋点之前,都应当先确定如何标识用户。distinct_id 是神策用来标识用户的一段唯一的字符串。

在小程序中,会有下面 3 种 id
1. 默认情况下,我们会生成一个随机数 uuid ,保存在 weixin storage 中,我们暂时称这个为 uuid
2. 用户打开小程序,我们可以获得用户的 weixin openid ,我们暂时称这个为 openid 
3. 客户用户账号体系中产生或保存的真实用户 id 。我们暂时称为 "你们服务端分配给用户具体的登录 ID"

由于调用 login() 接口之后,distinct_id 会由 uuid 变成真实 id,所以我们又提供了一个获取 weixin storage 中的 uuid 的方法:sa.quick('getAnonymousID'),返回 uuid (微信小程序版本 1.13.5 及以上支持)。

index.js

getApp().sensors.quick('getAnonymousID');
JS

2.1. 使用 openid 作为匿名 ID

如果不做任何操作,小程序会使用 uuid 作为 distinct_id ,但是这个 uuid 换了设备,或者删除小程序,会重新生成。所以一般情况下,我们建议使用 openid 作为当前的 distinct_id。因为获取 openid 是一个异步的操作,但是冷启动事件等会先发生,这时候这个冷启动事件的 distinct_id 就不对了。我们会把先发生的操作,暂存起来,等获取到 openid 后再调用 sa.init() 才会发数据。
下面是常见的两种使用 openid 作为匿名 ID 的初始化代码。

方案一

/**
	app.js
**/

var sa = require('sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址'
});
// 如果你们能获取到openid
sa.setOpenid(openid);
// 注意:init 不调用就不会发任何数据,确保无 openid 的时候也有 init 方法可执行
sa.init();
```
JS


注意:init 不调用就不会发任何数据,确保无 openid 的时候也有 init 方法可执行 

方案二

/**
	app.js
**/


var sa = require('sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址',
	appid: '在微信公众平台获取'
});
// 1、提供 appid 和 appsecret 给神策运维在后端做配置,
// 2、setPara() 方法中有 appid 的配置(如上)
sa.initWithOpenid();
JS

2.2. 匿名 ID 和用户 ID 关联

默认情况下 ,SDK 会分配一个匿名 ID (uuid) 来标识游客。当用户注册成功或登录成功时调用 login 方法,传入对应的用户 ID ;匿名 ID 会与对应的用户 ID 进行关联,关联成功之后视为同一个用户。 调用时机:注册成功、登录成功 、初始化 SDK(如果能获取到用户 ID)都需要调用 login 方法传入用户 ID。

app.js

var sa = require('sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址'
});
// 如果能获取到"你们服务端分配给用户具体的登录 ID",需要做用户关联情况下
sa.login("你们服务端分配给用户具体的登录 ID");
sa.init();
JS

3. 事件追踪

3.1. 事件公共属性 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

3.2. 预置事件

3.2.1. 预置事件追踪

为了方便使用, 0.9 版本以上的小程序 SDK 已经可以自动追踪微信小程序中的冷启动,热启动,进入后台,页面浏览,页面分享事件。

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

可以通过设置 setPara() 方法中的 autoTrack 参数,开启自动采集

app.js

var sa = require('sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址',
	autoTrack:{ 
		appLaunch:true, //是否采集 $MPLaunch 事件,true 代表开启。
		appShow:true, //是否采集 $MPShow 事件,true 代表开启。
		appHide:true, //是否采集 $MPHide 事件,true 代表开启。
		pageShow:true, //是否采集 $MPViewScreen 事件,true 代表开启。
		pageShare:true //是否采集 $MPShare 事件,true 代表开启。
	}
});
sa.init();
JS


注意事项:

  1. 1.13.6 版本之前的微信小程序 SDK 是通过代理监听小程序 Page 构造器与页面生命周期中的 onShareAppMessage() 函数来采集 $MPViewScreen $MPShare预置事件的。
  2. 当使用框架开发小程序时,如果框架代码在编译后使用的是 Component 构造器形成的页面,那么1.13.6 版本之前的微信小程序 SDK 无法自动采集该页面的预置事件 $MPViewScreen $MPShare,可以使用 track() 方法自定义采集

3.2.2. 预置事件设置自定义属性

用户可以在相应生命周期函数执行之前,对预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、$MPShare 添加自定义属性,可以通过为暴露出来的 sa.para.autoTrack 对象的相关属性设置一个属性值为对象或者返回值是对象的函数值实现。

示例:

app.js

/**
若用户想在 $MPLaunch 事件中添加appId,query等来源相关的自定义属性,可以通过下面方法实现
注意:该代码建议嵌入到相应js文件的顶部。
*/
var sa = require('./utils/sensorsdata.min.js');
sa.setPara({
name: 'sensors',
	server_url: '数据接收地址',
	autoTrack: {
		appLaunch : true,
		appShow : true,
		appHide : true,
		pageShow : true,
		pageShare : true
	}
});
sa.init();
App({
	onLaunch: function( data ){
		//给 $MPLaunch 事件添加自定义属性
		sa.para.autoTrack.appLaunch = {
			appId:data.referrerInfo.appId,
			query:data.query
		};
	},
	onShow: function( data ){
		//给 $MPShow 事件添加自定义属性
		sa.para.autoTrack.appShow = {
			appName: '神策小程序'
		}
	},
	onHide: function(){
		//给 $MPHide 事件添加自定义属性
		sa.para.autoTrack.appHide = {
			endTime: new Date()
		}
	}
})
JS

index.js

var app = getApp();
Page({
	onShow: function(){
		//给 $MPViewScreen 事件添加自定义属性
		app.sensors.para.autoTrack.pageShow = {
			pageName : '首页'
		}
	},
	onShareAppMessage: function(){
		app.sensors.para.autoTrack.pageShare = {
			sharePageName : '首页'
		}
	}
});
JS

3.3. 自定义事件追踪 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

4. 设置用户属性

4.1. setProfile(properties)

直接设置用户的属性,如果存在则覆盖。

  • properties:Object,必选。

app.js

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

4.2. setOnceProfile(properties)

如果不存在则设置,存在就不设置。

  • properties:Object,必选。

app.js

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

4.3. incrementProfile(properties)

增加或减少一个用户的某个 Numeric 类型的 Profile,如果该用户属性不存在则自动创建。

  • properties:Object,必选。

app.js

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

4.4. appendProfile(properties)

向某个用户的某个数组类型的 Profile 添加一个或者多个值。

  • properties:Object,必选。

app.js

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

5. 如何确认数据发送成功

5.1. 客户有测试项目(project=default)的情况下,优先建议客户使用测试项目的数据接收地址向测试项目发数据。

  • 集成 SDK 初始化代码且开启全埋点,验证数据接收地址;
  • 微信开发者工具 console 会打印采集的是数据,json 格式;

  • 微信开发者工具 network 中有 sa 的图片请求,且状态码为 200;
  • 神策分析界面中,打开导入中的数据,在浏览器刷新页面,有数据进入;

  • 神策分析界面中,打开埋点管理查看,已入库 1 条,证明数据采集成功;
  • 神策分析界面中,事件分析查看数据;

6. 实际案例使用

先把下载下来的 sensorsdata.min.js 放在根目录 untils 目录下

6.1. 在根目录的 app.js 中加入

app.js

// 这行是必须加入的
var sa = require('./utils/sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址'
});
/ 如果获取到用户的真实id信息
sa.login(userid);
// 如果获取到了用户的信息,可以给这个用户设置 profile
sa.setProfile({name:'tiantian',age:18});
sa.init();
App({
	onLaunch: function () {
		
	}
});
JS

6.2. 在 Pages 里的 js 中可以通过 getApp() 来获取 sensors

index.js

var app = getApp();
//下面模拟某个用户在浏览一张桃花的图片,当用户点击这张图片时,我们发送一个 clickImage 事件
Page({
	bindTapImage: function(){
		app.sensors.track('clickImage',{name:'桃花'});
	},
	onLoad: function(){

	}
});
JS