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

1. 快速使用

1.1.  集成与使用

1.1.1. 下载文件

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

  • 把文件放在小程序项目中,然后在 app.js 中通过 require() 引入文件 ;
  • 调用 setPara() 方法设置初始化参数,必须在 require() 之后,立即调用 setPara() 方法设置;
  • 调用 init() 方法标志已完成初始化;
    注意:init() 方法必须调用,否则不会发数据。

app.js

var sa = require('./utils/sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址',
	// 全埋点控制开关,设置为 false 就是不采集相应的预置事件
	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.1.3. 自定义事件采集

  • 通过调用 track() 接口来采集自定义事件

index.js

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

	}
});
JS

1.1.1. 安装 SDK

  • 通过 npm i sa-sdk-miniprogram 安装 SDK;

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

  • 在 main.js 中通过 import 引入 SDK;
  • 调用 setPara() 方法设置初始化参数;
  • 调用 init() 方法完成初始化;

main.js

import sa from 'sa-sdk-miniprogram'
import Vue from 'vue'
import App from './App'

sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址',
	// 全埋点控制开关,设置为 false 就是不采集相应的预置事件
	autoTrack: {
		appLaunch: true,
		appShow: true,
		appHide: true,
		pageShow: true,
		pageShare: true
	}
});
sa.init();

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
...App
})
app.$mount()
JS

1.1.3. 自定义事件采集

  • 在其他页面中通过调用 track() 接口采集自定义事件

label.vue

<script>
	export default {
		data() {
			return {
				
			}
		},
		methods: {
			radioChange: function(e) {
				//获取 App 实例,采集自定义事件
				getApp().sensors.track('labelChange',{
					currentValue: e.target.value
				})
				var checked = e.target.value
			}
		}
	}
</script>
JS

1.1.1. 安装 SDK

  • 通过 npm i sa-sdk-miniprogram 安装 SDK;

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

  • 在 app.jsx 中通过 import 引入 SDK;
  • 调用 setPara() 方法设置初始化参数;
  • 调用 init() 方法完成初始化;

app.tsc

import Taro, { Component } from '@tarojs/taro'
import Index from './pages/index'

import sa from 'sa-sdk-miniprogram'
sa.setPara({
	name:'sensors',
	server_url: '数据接收地址',
  	// 全埋点控制开关,设置为 false 就是不采集相应的预置事件
	autoTrack: {
		appLaunch: true,
		appShow: true,
		appHide: true,
		pageShow: true,
		pageShare: true
	}
});
sa.init();

class App extends Component {

  config = {
    pages: [
      'pages/index/index'
    ]
  }
 
  render () {
    return (
      <Index />
    )
  }
}

Taro.render(<App />, document.getElementById('app'))
JS

1.1.3. 自定义事件采集

  • 在其他页面中通过调用 track() 接口采集自定义事件

index.jsx

import Taro, { Component } from '@tarojs/taro'
import { View, Text, Button } from '@tarojs/components'
export default class Index extends Component {

  config = {
    navigationBarTitleText: '首页'
  }


  handleClick= ()=>{
    //获取 App 实例,采集自定义事件
    Taro.getApp().sensors.track('click',{
      name:'点击'
    })
  }

  render () {
    return (
      <View className='index'>
        <Text>Hello world!</Text>
        <Button onClick={this.handleClick}>点击</Button>
      </View>
    )
  }
}
JS

1.1.1. 安装 SDK

  • 通过 npm i sa-sdk-miniprogram 安装 SDK;

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

  • 在 main.js 中通过 import 引入 SDK,sensorsdata.js 需要在 vue 之前引入;
  • 调用 setPara() 方法设置初始化参数;
  • 调用 init() 方法完成初始化;

main.js

import sa from 'sa-sdk-miniprogram'
import Vue from 'vue'
import App from './App'
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址',
	// 全埋点控制开关,设置为 false 就是不采集相应的预置事件
	autoTrack: {
		appLaunch: true,
		appShow: true,
		appHide: true,
		pageShow: true,
		pageShare: true
	}
});
sa.init();
JS

1.1.3. 自定义事件采集

  • 在其他页面中通过调用 track() 接口采集自定义事件

index.vue

<template>
  <div @click="clickHandle">
    <button>点击</button>
  </div>
</template>

<script>

export default {
  data () {
    return {
      
    }
  },

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

  created () {
    
  }
}
</script>
JS

1.1.1. 安装 SDK

  • 通过 npm i sa-sdk-miniprogram 安装 SDK;

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

  • 在 app.wpy 中通过 import 引入 SDK;
  • 调用 setPara() 方法设置初始化参数;
  • 调用 init() 方法完成初始化;

app.wpy

import wepy from 'wepy'

import sa from 'sa-sdk-miniprogram'
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址',
	// 全埋点控制开关,设置为 false 就是不采集相应的预置事件
	autoTrack: {
		appLaunch: true,
		appShow: true,
		appHide: true,
		pageShow: true,
		pageShare: true
	}
});
sa.init();

wepy.app({

});
JS

1.1.3. 自定义事件采集

  • 在其他页面中通过调用 track() 接口采集自定义事件

index.wpy

wepy.page({
	onShow(){
		//获取 App 实例,采集自定义事件
		getApp().sensors.track('show');
	}
})
JS

1.2. 确认数据发送成功

注意:客户有测试项目的情况下,优先建议客户使用测试项目的数据接收地址向测试项目发数据。

  • 集成 SDK 初始化代码且使用 track() 方法进行埋点,微信开发者工具 console 会打印采集的数据,json 格式;

  • 微信开发者工具 network 中有 sa 的图片请求,且状态码为 200,验证数据接收地址;

  • 神策分析界面中,打开导入中的数据,点击开始刷新按钮。在微信开发者工具触发一些事件,分析后台的导入中数据可以看到数据进入;

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

2. 标识用户

如何准确的标识用户

在进行任何埋点之前,都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中,会有下面 3 种 ID:

  1. 默认情况下,微信小程序 SDK 会生成一个唯一的随机数,保存在微信 storage 中,我们称这个为 UUID;
  2. 用户打开小游戏,可以获得微信分配给用户的 openid ,我们称这个为 openid;
  3. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";

2.1. 使用 openid 作为匿名 ID

如果不做任何操作,小程序会使用 UUID 作为 Distinct ID,但是这个 UUID 换了设备,或者删除小程序后,会重新生成。所以一般情况下,我们建议使用 openid 作为当前的 Distinct ID。

下面是常见的两种使用 openid 作为匿名 ID 的初始化代码。

方案一

/**
	app.js
**/

var sa = require('sensorsdata.min.js');
sa.setPara({
    name: 'sensors',
    server_url: '数据接收地址'
});
// 获取到 openid 代码,代码逻辑仅供参考
wx.request({
    url: '获取 openid 的后端接口',
    success: function(res){
        // 设置 openid 作为匿名 ID
        sa.setOpenid(res.openid);
    }
    complete: function(){
        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: '数据接收地址'
});
/**
    场景一 使用 openid 作为匿名 ID,且需要做用户关联
          代码逻辑仅供参考
**/
wx.request({
    url: '获取 openid 的后端接口',
    success: function(res){
        // 设置 openid 作为匿名 ID
        sa.setOpenid(res.openid);  
    },
    complete: function(){
        if(如果能获取到"你们服务端分配给用户具体的登录 ID",需要做用户关联情况下){
            sa.login("你们服务端分配给用户具体的登录 ID");
        }
        sa.init();
    }
});
 
/**
    场景二 使用 UUID 作为匿名 ID,且需要做用户关联
          代码逻辑仅供参考
**/
if(如果能获取到"你们服务端分配给用户具体的登录 ID",需要做用户关联情况下){
    sa.login("你们服务端分配给用户具体的登录 ID");
}
sa.init();
JS

3. 预置事件

为了方便使用, 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() 方法自定义采集;

4. 预置属性

4.1. 所有事件都有的预置属性

该表格中的预置属性是微信小程序 SDK 采集的所有事件都有的预置属性;

注意:此表格中的预置属性加上小程序 SDK 预置属性文档中所有事件都有的预置属性才是完整的微信小程序 SDK 采集的所有事件都有的预置属性;

字段名称类型说明SDK 版本
$latest_utm_source字符串最近一次付费广告系列来源1.3 支持
$latest_utm_medium字符串最近一次付费广告系列媒介1.3 支持
$latest_utm_term字符串最近一次付费广告系列字词1.3 支持
$latest_utm_content字符串最近一次付费广告系列内容1.3 支持
$latest_utm_campaign字符串最近一次付费广告系列名称1.3 支持
$latest_scene字符串最近一次启动场景值1.9 支持

4.2. 预置事件独有的预置属性

4.2.1. 预置事件 $MPLaunch 独有的预置属性

该表格中的预置属性是微信小程序 SDK 采集的预置事件 $MPLaunch 独有的预置属性;

注意:此表格中的预置属性加上小程序 SDK 预置属性文档中所有小程序 SDK 预置事件 $MPLaunch 都有的预置属性才是完整的微信小程序 SDK 采集的预置事件 $MPLaunch 独有的预置属性;

字段名称类型说明SDK 版本
$utm_source字符串广告系列来源0.9 以上
$utm_medium字符串广告系列媒介0.9 以上
$utm_term字符串广告系列字词0.9 以上
$utm_content字符串广告系列内容0.9 以上
$utm_campaign字符串广告系列名称0.9 以上
$share_distinct_id字符串分享时的 distinct_id1.9 以上
$share_depth数值分享层级1.9 以上
$share_url_path字符串分享时的页面路径1.9 以上
$url_query字符串页面参数1.10.4 以上

4.2.2. 预置事件 $MPShow 独有的预置属性

该表格中的预置属性是微信小程序 SDK 采集的预置事件 $MPShow 独有的预置属性;

注意:此表格中的预置属性加上小程序 SDK 预置属性文档中所有小程序 SDK 预置事件 $MPShow 都有的预置属性才是完整的微信小程序 SDK 采集的预置事件 $MPShow 独有的预置属性;

字段名称类型说明SDK 版本
$utm_source字符串广告系列来源0.9 以上
$utm_medium字符串广告系列媒介0.9 以上
$utm_term字符串广告系列字词0.9 以上
$utm_content字符串广告系列内容0.9 以上
$utm_campaign字符串广告系列名称0.9 以上
$share_distinct_id字符串分享时的 distinct_id1.9 以上
$share_depth数值分享层级1.9 以上
$share_url_path字符串分享时的页面路径1.9 以上
$url_query字符串页面参数1.10.4 以上

4.2.3. 预置事件 $MPHide 独有的预置属性

该表格中的预置属性是微信小程序 SDK 采集的预置事件 $MPHide 独有的预置属性;

注意:此表格中的预置属性加上小程序 SDK 预置属性文档中所有小程序 SDK 预置事件 $MPHide 都有的预置属性才是完整的微信小程序 SDK 采集的预置事件 $MPHide 独有的预置属性;

字段名称类型说明SDK 版本
$url_path字符串页面路径

4.2.4. $MPViewScreen 预置事件独有的预置属性

字段名称类型说明SDK 版本
$utm_term字符串广告系列字词0.9 以上,1.12.10 版本以下,1.13.7 以上
$utm_source字符串广告系列来源0.9 以上,1.12.10 版本以下,1.13.7 以上
$utm_medium字符串广告系列媒介0.9 以上,1.12.10 版本以下,1.13.7 以上
$utm_content字符串广告系列内容0.9 以上,1.12.10 版本以下,1.13.7 以上
$utm_campaign字符串广告系列名称0.9 以上,1.12.10 版本以下,1.13.7 以上
$url_query字符串页面参数,比如小程序页面路径为 page/index/index?ceshi=bar,那么页面参数为 ceshi=bar1.10.4 版本以上
$url_path字符串页面路径0.9 版本之前为 $url
$referrer字符串前向页面地址0.9 版本以上

4.2.5. $MPShare 预置事件独有的预置属性

字段名称类型说明SDK 版本
$share_depth数值分享层级1.9 版本以上
$url_path字符串分享时的页面路径1.9 版本以上

4.3. 预置用户属性

当用户首次访问集成了 SDK 的小程序时,微信小程序 SDK 会自动采集以下用户属性

字段名称类型说明
$first_visit_time日期首次访问时间
$utm_source字符串首次访问广告系列来源
$utm_medium字符串首次访问广告系列媒介
$utm_term字符串首次访问广告系列字词
$utm_content字符串首次访问广告系列内容
$utm_campaign字符串首次访问广告系列名称

5. 实际案例使用

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

5.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

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

index.js

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

	}
});
JS