在使用前,请先阅读数据模型的介绍。

更新日志

1. 快速使用

1.1. 集成与使用

1.1.1. 下载 SDK

1.1.2. 引入并配置参数

  • 把文件放在小程序项目中,然后在 app.js 中通过 require() 引入文件 ;
  • 调用 setPara() 方法设置初始化参数(必须在 require() 之后,立即调用 setPara() 方法设置
  • 在 App 函数中设置一个全局变量,如:sensors,以便其他 js 文件中通过该全局变量调用 SDK 接口;

app.js

// 此处 sensorsdata.min.js 文件路径需要根据项目实际情况设置
var sa = require('./sdk/sensorsdata.min.js')
sa.setPara({
	server_url: '数据接收地址'
});
App({ 
	onLaunch : function(){ 
		// 设置全局变量
		this.sensors = sa 
	}
})
JS

1.1.3. 开启全埋点

  • 在小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点,采集预置事件

app.js

var sa = require('./sdk/sensorsdata.min.js')
sa.setPara({
	server_url: '数据接收地址'
});
App({
	onLaunch : function( options ){
		this.sensors = sa;
       //通过调用 quick() 接口且设置第一个参数为 appLaunch,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPLaunch,第三个参数是要为该事件设置的属性对象 
		sa.quick('appLaunch', options,{
			ProductId: '123456'
		});
	},
	onShow : function( options ){
      //通过调用 quick() 接口且设置第一个参数为 appShow,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPShow,第三个参数是要为该事件设置的属性对象 
		sa.quick('appShow', options,{
			ProductCatalog: "Laptop Computer"
		});
	},
	onHide : function(){
	 //通过调用 quick() 接口且设置第一个参数为 appHide,第二个参数是要为该事件设置的属性对象
		sa.quick('appHide',{
			ProductName: "MacBook Pro"
		});
	}
});
JS

1.1.4. 自定义事件采集

  • 其他 js 文件中可以通过 track() 方法来采集自定义事件数据

index.js

// 获取小程序 App 实例
var app = getApp();
Page({
	onShow: function(){
		// 通过 1.1.2. 步骤中为小程序实例对象上挂载的 sensors 对象调用 track() 接口采集自定义事件
		app.sensors.track('pageView',{
			pagename: 'index'
		})
	}
});
JS

1.1.1. 下载 SDK

1.1.2. 引入并配置参数

  • 把文件放在小程序项目中,然后在 main.js 中通过 import 引入文件 ;
  • 调用 setPara() 方法设置初始化参数
  • 设置全局变量,如:sensors,以便在页面中通过该全局变量调用 SDK 接口;

main.js

import Vue from 'vue'
import App from './App'

// #ifdef MP-QQ
// 此处 sensorsdata.min.js 文件路径需要根据项目实际情况设置
import sa from './sensorsdata.min.js'
sa.setPara({
	server_url: '数据接收地址'
});
//其他全局变量方式可参考此官方文档 https://ask.dcloud.net.cn/article/35021
Vue.prototype.sensors = sa;
//#endif

Vue.config.productionTip = false

App.mpType = 'app'

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

1.1.3. 开启全埋点

  • 在 App.vue 文件中的小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点,采集预置事件

App.vue

<script>
    export default {  
        onLaunch: function(option) {            
        	//通过调用 quick() 接口且设置第一个参数为 appLaunch,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPLaunch,第三个参数是要为该事件设置的属性对象
        	this.sensors.quick('appLaunch', option);           
        },
        onShow: function( option ) {            
            //通过调用 quick() 接口且设置第一个参数为 appShow,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPShow,第三个参数是要为该事件设置的属性对象    
        	this.sensors.quick('appShow', option)           
        },
        onHide: function() {
            //通过调用 quick() 接口且设置第一个参数为 appHide,第二个参数是要为该事件设置的属性对象来采集预置事件 $MPHide
        	this.sensors.quick('appHide')
        },
		globalData: {
			test: ''
		}
    }
</script>
JS

1.1.4. 自定义事件采集

  • 其他页面中可以通过 track() 方法来采集自定义事件数据

lable.vue

<script>
	export default {
		data() {
			return {};
		},
		methods: {
			radioChange: function(e) {
				var checked = e.target.value
				// 采集自定义事件
				this.sensors.track('labelChange',{
					currentValue: checked
				})
				console.log(checked)
			}
		}
	}
</script>
JS

1.1.1. 下载 SDK

1.1.2. 引入并配置参数

  • 把文件放在小程序项目中,然后在 app.jsx 中通过 import 引入文件 ;
  • 调用 setPara() 方法设置初始化参数
  • 在 App 类中设置一个全局变量,如:sensors,以便其他 jsx 文件中通过该全局变量调用 SDK 接口;

app.jsx

import Taro, { Component } from '@tarojs/taro'
import Index from './pages/index'
// 此处 sensorsdata.min.js 文件路径需要根据项目实际情况设置
import sa from './util/sensorsdata.min.js'
sa.setPara({
  server_url: '数据接收地址'
});
class App extends Component {
	config = {
    	pages: [
      		'pages/index/index'
    	],
    	window: {
      		backgroundTextStyle: 'light',
      		navigationBarBackgroundColor: '#fff',
      		navigationBarTitleText: 'WeChat',
      		navigationBarTextStyle: 'black'
    	}
  	}

	constructor(){
		super();
		// 设置全局变量
		this.sensors = sa;
	}
  	
}
JS

1.1.3. 开启全埋点

  • 在小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点,采集预置事件

app.jsx

import Taro, { Component } from '@tarojs/taro'
import Index from './pages/index'
import sa from './util/sensorsdata.min.js'
sa.setPara({
  server_url: '数据接收地址'
});

class App extends Component {

  config = {
    pages: [
      'pages/index/index'
    ],
    window: {
      backgroundTextStyle: 'light',
      navigationBarBackgroundColor: '#fff',
      navigationBarTitleText: 'WeChat',
      navigationBarTextStyle: 'black'
    }
  }
	constructor(){
		super();
		// 设置全局变量
		this.sensors = sa;
	}

  componentDidMount () {
    //通过调用 quick() 接口且设置第一个参数为 appLaunch,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPLaunch,第三个参数是要为该事件设置的属性对象
    sa.quick('appLaunch', this.$router.params);
  }

  componentDidShow () {
	//通过调用 quick() 接口且设置第一个参数为 appShow,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPShow,第三个参数是要为该事件设置的属性对象    
    sa.quick('appShow', this.$router.params);
  }

  componentDidHide () {
	//通过调用 quick() 接口且设置第一个参数为 appHide,第二个参数是要为该事件设置的属性对象来采集预置事件 $MPHide
    sa.quick('appHide');
  }

  render () {
    return (
      <Index />
    )
  }
}

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

1.1.4. 自定义事件采集

  • 其他 jsx 文件中可以通过 track() 方法来采集自定义事件数据

index.jsx

import Taro, { Component } from '@tarojs/taro'
import { View, Text, Button } from '@tarojs/components'
import './index.css'

export default class Index extends Component {

  config = {
    navigationBarTitleText: '首页'
  }

  componentWillMount () { }

  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.2. 确认数据发送成功

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

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

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

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

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

2. 标识用户

如何准确的标识用户

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

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

2.1. 匿名 ID 和用户 ID 关联

默认情况下,SDK 会分配一个匿名 ID(UUID) 来标识用户。当用户注册或登录成功时,调用 login() 方法,传入对应的用户 ID;匿名 ID 会与对应的用户 ID 进行关联,关联成功之后视为同一个用户。

调用时机:注册成功、登录成功、初始化 SDK (如果能获取到用户 ID)都需要调用 login() 方法传入用户 ID。

app.js

var sa = require('./sdk/sensorsdata.min.js')
sa.setPara({
	server_url: '数据接收地址'
});

/**
    使用 UUID 作为匿名 ID,且需要做用户关联
    代码逻辑仅供参考
**/
if(如果能获取到"你们服务端分配给用户具体的登录 ID",需要做用户关联情况下){
    sa.login("你们服务端分配给用户具体的登录 ID");
}

App({
	onLaunch: function( options ){
		this.sensors = sa;
		sa.quick('appLaunch', options)
	}
});
JS

3. 预置事件

小程序支持采集 $MPLaunch、$MPShow、$MPHide 这三个预置事件。

事件名称

相应小程序生命周期

触发时机

说明

$MPLaunch(小程序启动)App.onLaunch小程序进程被杀死,重新打开且在相应小程序生命周期函数中调用了 sa.quick( 'appLaunch', options ) 时会触发小程序初始化完成时,全局只触发一次
$MPShow(小程序显示)App.onShow小程序启动,或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick( 'appShow', options ) 时会触发启动小程序时
$MPHide(小程序进入后台)App.onHide点击小程序右上角退出按钮、QQ 进入后台、进入小程序关于页面、手机锁屏、小程序进程被杀死且在相应小程序生命周期函数中调用了 sa.quick( 'Hide' ) 时会触发时小程序从前台进入后台

app.js

var sa = require('./sdk/sensorsdata.min.js')
sa.setPara({
	server_url: '数据接收地址'
});
App({
	onLaunch : function( options ){
		this.sensors = sa;
       //通过 quick() 接口且设置第一个参数为 appLaunch,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPLaunch,第三个参数是要为该事件设置的属性对象 
		sa.quick('appLaunch', options,{
			ProductId: '123456'
		});
	},
	onShow : function( options ){
      //通过 quick() 接口且设置第一个参数为 appShow,第二个参数为生命周期回调函数参数对象来采集预置事件 $MPShow,第三个参数是要为该事件设置的属性对象 
		sa.quick('appShow', options,{
			ProductCatalog: "Laptop Computer"
		});
	},
	onHide : function(){
	 //通过 quick() 接口且设置第一个参数为 appHide,第二个参数是要为该事件设置的属性对象
		sa.quick('appHide',{
			ProductName: "MacBook Pro"
		});
	}
});
JS

4. 常用 API

4.1. 采集事件数据 API

4.1.1. track(eventName,[properties])

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

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

index.js

var app = getApp();
app.sensors.track('ViewProduct', {
	ProductId: '123456',
	ProductCatalog: "Laptop Computer",
	ProductName: "MacBook Pro",
	ProductPrice: 12345
}); 
JS

4.1.2. login( userID );

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

4.1.3. registerApp(properties)

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

app.js

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

4.2. 采集用户数据 API

4.2.1. setProfile(properties)

  • 说明:用来设置用户的属性,如果存在同名属性则覆盖。
  • 参数:
    • properties: Object,必选,要设置的用户属性;

app.js

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

4.2.2. setOnceProfile(properties)

  • 说明:用来设置用户的属性,如果不存在该属性则设置,存在同名属性不覆盖。
  • 参数:
    • properties: Object,必选,要设置的用户属性;

app.js

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

4.3. 其他 API

4.3.1. identify( anonymousID, [boolean]);

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

4.3.2. getPresetProperties();

  • 说明:用来获取部分预置属性;由于部分预置属性是异步获取到的,所以 init() 之后立即调用该方法会只返回部分属性。
  • Returns: Object
    • 返回一个包含屏幕宽高、网络类型、操作系统、操作系统版本、设备制造商、设备型号、SDK 版本属性的对象

5. 预置属性

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

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

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

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

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

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

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

注意:

字段名称类型说明
$utm_source字符串广告系列来源
$utm_medium字符串广告系列媒介
$utm_term字符串广告系列字词
$utm_content字符串广告系列内容
$utm_campaign字符串广告系列名称

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

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

注意:

字段名称类型说明
$utm_source字符串广告系列来源
$utm_medium字符串广告系列媒介
$utm_term字符串广告系列字词
$utm_content字符串广告系列内容
$utm_campaign字符串广告系列名称

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

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

注意:

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

5.3. 预置用户属性

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

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

6. 渠道追踪

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

7. 实际案例使用

app.js

var sa = require('./sdk/sensorsdata.min.js')
sa.setPara({
	server_url: '数据接收地址'
});
//设置公共属性
sa.registerApp({
	platform: 'QQMini'
});
/**
    使用 UUID 作为匿名 ID,且需要做用户关联
    代码逻辑仅供参考
**/
if(如果能获取到"你们服务端分配给用户具体的登录 ID",需要做用户关联情况下){
    sa.login("你们服务端分配给用户具体的登录 ID");
}
App({
	onLaunch : function( options ){
		//设置全局变量
		this.sensors = sa;
		//采集预置事件
		sa.quick('appLaunch', options, {
			appName : '神策分析小程序'
		});
	},
	onShow : function( options ){
		sa.quick('appShow', options, {
			showTime : new Date()
		});
	},
	onHide : function(){
		sa.quick('appHide', {
			eventDuration : 5000
		});
	}
});
JS

index.js

var app = getApp();
Page({
	onShow: function(){
		//使用 track() 方法采集自定义页面浏览事件
		app.sensors.track('MPViewScreen',{
			pageTitle: '首页'
		});
	}
});
JS