微信小程序 SDK (历史版)使用说明

最后更新于:2019-07-10 10:33:34

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

更新日志

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

1.1 下载 sdk

从 github 上下载 微信小程序 sdk ,sensorsdata.min.js 和 sensorsdata_conf.js

把这两个文件放在小程序的 utils 目录下,然后在 app.js 第一行添加以下代码

var sensors = require('./utils/sensorsdata.min.js');
sensors.init();

现在在其他 Page 里就可以通过 getApp 来使用神策的追踪了

var app = getApp();
app.sensors.track(eventName, properties) // 第一个参数事件名 字符串类型,第二个参数 属性值 对象类型

1.2 sensorsdata_conf.js 参数配置

  • name: SDK 使用的一个默认的全局变量,会注册在 App 全局函数内,在 Page 中可以通过 app[name].track 来使用,默认值是 sensors 。

  • appid: (非必填参数)如果需要自动获取 openid ,需要在神策后端配置 appid 和 appsecret ,同时在这里指定 appid 。

  • server_url: 数据接收地址, 注意: 请在微信开发设置,服务器域名的 request 合法域名内,把这个地址加上。

  • send_timeout: 请求发送超时时间(如果一个请求发送后,超过规定时间没响应,则继续发送下一条数据),默认为 1000 毫秒。

  • use_client_time: 因为客户端系统时间的不准确,会导致发生这个事件的时间有误,所以这里默认为 false ,表示不使用客户端时间,使用服务端时间,如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ,注意这里必须是 Date 类型,那么这条数据就会使用你在属性中传入的这个时间。

  • autoTrack: 是否开启自动采集,五个参数的值默认为 true,即采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare(0.9以上版本的 SDK 支持,其中 $MPShare 事件1.9版本以上支持,详细介绍见本页第四点)。

  • show_log: 设置 true 后会在模拟器控制台打 logger,会显示发送的数据,设置 false 表示不显示。默认为 true 。

  • allow_amend_share_path: 设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性,新增一些参数包括当前用户的 distinct_id 等,如果要自动采集分享,必须设置为 true 。

  • is_plugin: 小程序中是否使用了插件,默认为 false 。小程序中如果使用了插件,该参数必须设置为 true 。

  • batch_send: 小程序中是否使用批量发送数据功能,默认为 false ,配置注意事项详见常见问题 9.7

  • datasend_timeout: 请求发送取消时间(请求发送后,在规定时间内未返回结果,则取消请求),默认为 1000 毫秒(1.12.9 及以上版本支持) 。

1.3 mpvue 小程序框架集成 SDK

1.3.1 集成与初始化

第一步:从 github 上下载 微信小程序 sdk ,sensorsdata.js 和 sensorsdata_conf.js (其中未压缩的 sensorsdata.js 文件请联系神策值班同学获取)
第二步:将 sensorsdata_conf.js 中的导出方式代码 module.exports = conf;修改为 export { conf };
第三步:修改 sensorsdata.js ,将sa.para = require('sensorsdata_conf.js'); 修改为 import { conf } from './sensorsdata_conf'; sa.para = conf;
module.exports = sa; 修改为 export { sa };
第四步:将修改好的文件放到小程序项目的 utils 目录下
第五步:在项目的 main.js 中引入 SDK,sensorsdata.min.js 必须在 vue 之前引入,然后初始化

import { sa } from './utils/sensorsdata'
import Vue from 'vue'
import App from './App'

sa.init();

1.3.2 Page 中追踪自定义事件

const app = getApp()
export default {
  data () {
    return {}
  },

  methods: {
    eventSend(){
      app.sensors.track('事件名称',{
        '属性名1' : '属性值1',
        '属性名2' : '属性值2',
        '...' : '...'
      })
    }
  }
}

1.4 wepy 小程序框架集成 SDK

第一步:通过 npm i sa-sdk-miniprogram集成 SDK
第二步:修改 src 目录下的 app.wpy,在 app.wpy 中引入 SDK

import sa from 'sa-sdk-miniprogram'
import wepy from 'wepy'
import 'wepy-async-function'
import { setStore } from 'wepy-redux'
import configStore from './store'

sa.init()

2. 用户标识

相关文档链接:

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

在小程序中,会有下面 3 种 id

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

2.1 使用 openid

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

-------app.js  

var sensors = require('sensorsdata.min.js');
// 如果你们能获取到openid
sensors.setOpenid(openid);
sensors.init();
-------app.js  

var sensors = require('sensorsdata.min.js');
// 如果后端做了 appid 和 appsecret 的配置,以及 sensorsdata_conf 里有 appid 的配置
sensors.initWithOpenid();

2.2 匿名 ID 和用户 ID 关联

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

-------app.js  

var sensors = require('sensorsdata.min.js');
// 如果能获取到"你们服务端分配给用户具体的登录 ID",需要做用户关联情况下
sensors.login("你们服务端分配给用户具体的登录 ID");
sensors.init();

3. 自定义事件追踪

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

电商产品,可以追踪用户注册、浏览商品和下订单等事件。

    // 追踪浏览商品事件。  
    var app = getApp();
    app.sensors.track('ViewProduct', {
        ProductId: '123456',
        ProductCatalog: "Laptop Computer",
        ProductName: "MacBook Pro",
        ProductPrice: 12345
    });

事件公共属性:可以在 app.js 文件引入 sensorsdata.min.js 文件之后, init() 方法调用之前使用 registerApp() 方法设置公共属性。例如:

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

4 预置事件

4.1 预置事件追踪

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

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

例如:在 sensorsdata_conf.js 中添加下面参数,开启 autoTrack 自动采集

  autoTrack:{  
    appLaunch:true, //是否采集 $MPLaunch 事件,true 代表开启。
    appShow:true, //是否采集 $MPShow 事件,true 代表开启。
    appHide:true, //是否采集 $MPHide 事件,true 代表开启。
    pageShow:true, //是否采集 $MPViewScreen 事件,true 代表开启。
    pageShare:true //是否采集 $MPShare 事件,true 代表开启。
  }

4.2 预置事件自定义属性

用户可以在预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen 等中通过 getApp().sensors.para.autoTrack[param] = value添加自定义属性,其中 param 为 appLaunch, appShow, appHide, pageShow 等; value 为对象或返回值是对象的函数;

例如:

    若用户想在 $MPLaunch 事件中添加appId,query,extraData等来源相关的自定义属性,可以通过下面方法实现
    var sa = require('./utils/sensorsdata.min.js');
    App({
        onLaunch: function (data) {
            sa.para.autoTrack.appLaunch={
                    appId:data.referrerInfo.appId,
                    query:data.query,
                    extraData:data.referrerInfo.extraData
                }
            …………

    或通过一个返回对象的函数实现
    var sa = require('./utils/sensorsdata.min.js');
    App({
        onLaunch: function (data) {
            sa.para.autoTrack.appLaunch=function(){
                return {
                    appId:data.referrerInfo.appId,
                    query:data.query,
                    extraData:data.referrerInfo.extraData
                }
            }
            …………

注意:该代码建议嵌入到相应js文件的顶部。

5 渠道相关问题

5.1 utm 相关属性

在小程序冷启动 appLaunch 和热启动 appShow 还有页面打开 pageShow,我们会自动解析普通网页二维码的 utm 参数 解析 utm 相关的属性 作为这 3 个事件的属性

5.2 $latest_utm 相关属性

在冷启动 appLaunch 里解析出来的 utm 值,会在小程序的生命周期内,用 $latest_utm 相关属性来一直保存着
在热启动 appShow 中如果有新的 utm 参数时, $latest_utm 值会覆盖
在下次重新冷启动的时候, $latest_utm 的值会重置,如果没有就不会有这个属性

5.3 首次 utm 的相关属性

在小程序 sdk 发现设备之前没有加载过 sdk ,且如果冷启动 appLaunch 能解析到 utm 值时,会 setOnceProfile 来设置用户属性

5.4 utm 相关属性解析时机

通过普通网页二维码进入小程序,appLaunch 和 appShow 会根据 query.q 来解析 utm 相关参数。

通过小程序码或分享到好友等方式进入小程序,appLaunch 和 appShow 会根据 query 来解析 utm 相关参数。

通过小程序跳转小程序,appLaunch 和 appShow 会根据 referrerInfo.extraData 来解析 utm 相关参数。

$latest_utm 相关属性取值时机、首次 utm 相关属性取值时机与其一致。

6 预置属性

6.1 所有事件都有的预置属性:

字段名称 类型 说明 版本
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 小程序屏幕高度
$screen_width 数值 小程序屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商 1.11.1 支持
$network_type 字符串 网络类型
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类型 是否首日访问(从新用户第一次访问到当天的凌晨十二点之间的值都为真,之后都为假,标识存在 storage 缓存中)
$ip 字符串 SDK 发送数据请求携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$latest_utm_source 字符串 最近一次付费广告系列来源(参考本章文档 5.1-5.4 的解释) 1.3 支持
$latest_utm_medium 字符串 最近一次付费广告系列媒介(参考本章文档 5.1-5.4 的解释) 1.3 支持
$latest_utm_term 字符串 最近一次付费广告系列字词(参考本章文档 5.1-5.4 的解释) 1.3 支持
$latest_utm_content 字符串 最近一次付费广告系列内容(参考本章文档 5.1-5.4 的解释) 1.3 支持
$latest_utm_campaign 字符串 最近一次付费广告系列名称(参考本章文档 5.1-5.4 的解释) 1.3 支持
$latest_scene 字符串 最近一次启动场景值 1.9 支持

6.1.1 UserAgent 相关的预置属性

这一系列的属性从浏览器的 UserAgent 中进行解析。

字段名称 类型 说明 版本
$bot_name 字符串 爬虫名称(如果是爬虫)

注意:
1.$screen_height 在 1.11.1 版本之前字段名称为‘小程序窗口高度’,取的值是小程序可使用窗口高度
2.$screen_width 在 1.11.1 版本之前字段名称为‘小程序窗口宽度’,取的值是小程序可使用窗口宽度
3.wx.getSystemInfo 微信小程序提供的接口获取系统信息。

6.2 $MPLaunch (小程序启动)事件的预置属性:

字段名称 类型 说明 版本
$scene 字符串 启动场景 1.0以上
$url_path 字符串 页面路径
$utm_source 字符串 广告系列来源(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_medium 字符串 广告系列媒介(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_term 字符串 广告系列字词(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_content 字符串 广告系列内容(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_campaign 字符串 广告系列名称(参考本章文档 5.1-5.4 的解释) 0.9以上
$is_first_time 布尔类型 是否首次访问,新用户首次触发这个事件标识为真 1.8以上
$share_distinct_id 字符串 分享时的 distinct_id 1.9以上
$share_depth 数值 分享次数 1.9以上
$share_url_path 字符串 分享时的页面路径 1.9以上
$url_query 字符串 页面参数 1.10.4以上

其中场景值的概念及取值可以参考微信小程序的官方介绍场景值

6.3 $MPShow (小程序显示)事件的预置属性:

字段名称 类型 说明 版本
$scene 字符串 启动场景 1.0以上
$url_path 字符串 页面路径
$utm_source 字符串 广告系列来源(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_medium 字符串 广告系列媒介(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_term 字符串 广告系列字词(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_content 字符串 广告系列内容(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_campaign 字符串 广告系列名称(参考本章文档 5.1-5.4 的解释) 0.9以上
$share_distinct_id 字符串 分享时的 distinct_id 1.9以上
$share_depth 数值 分享次数 1.9以上
$share_url_path 字符串 分享时的页面路径 1.9以上
$url_query 字符串 页面参数 1.10.4以上

6.4 $MPHide (小程序进入后台)事件的预置属性:

字段名称 类型 说明 版本
event_duration NUMBER 从本次小程序显示 $MPShow 到 $MPHide 小程序进入后台或者关闭的时间 1.1及以上
$url_path 字符串 页面路径 1.5及以上

6.5 $MPViewScreen (小程序页面浏览)事件的预置属性:

字段名称 类型 说明 版本
$url_path 字符串 页面路径 0.9版本之前为 $url
$referrer 字符串 前向页面地址 0.9以上
$utm_source 字符串 广告系列来源(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_medium 字符串 广告系列媒介(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_term 字符串 广告系列字词(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_content 字符串 广告系列内容(参考本章文档 5.1-5.4 的解释) 0.9以上
$utm_campaign 字符串 广告系列名称(参考本章文档 5.1-5.4 的解释) 0.9以上
$url_query 字符串 页面参数,比如小程序页面路径为 page/index/index?ceshi=bar,那么页面参数为 ceshi=bar 1.10.4以上

6.6 $MPShare (小程序分享)事件的预置属性:

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

6.7 预置的用户属性

字段名称 类型 说明 版本
$first_visit_time Datetime 首次访问时间,新用户第一次来到嵌有神策 SDK 微信小程序的客户端时间 1.12.9 及以上版本
$utm_source 字符串 首次广告系列来源 (参考本章文档 5.3 的解释) 1.0 及以上版本
$utm_medium 字符串 首次广告系列媒介 (参考本章文档 5.3 的解释) 1.0 及以上版本
$utm_term 字符串 首次广告系列字词 (参考本章文档 5.3 的解释) 1.0 及以上版本
$utm_content 字符串 首次广告系列内容 (参考本章文档 5.3 的解释) 1.0 及以上版本
$utm_campaign 字符串 首次广告系列名称 (参考本章文档 5.3 的解释) 1.0 及以上版本

7 设置用户属性

7.1 sensors.setProfile(properties)

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

  • properties:object,必选。
    sensors.setProfile({email:'xxx@xx'});

7.2 sensors.setOnceProfile(properties)

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

  • properties:object,必选。
    sensors.setOnceProfile({email:'xxx@xx'});

8 实际案例使用

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

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

// 这行是必须加入的
var sensors = require('./utils/sensorsdata.min.js');

App({
  onLaunch: function () {
          // 如果获取到用户的真实id信息
          sensors.login(userid);
          // 如果获取到了用户的信息,可以给这个用户设置 profile
          sensors.setProfile({name:'tiantian',age:18});
  }
  ......
});

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

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

  }
});

9 常见问题

9.1 小程序中服务器域名设置

  • 小程序 server_url (数据接收地址)需要在微信公众平台---开发---开发设置---服务器域名中配置
  • 小程序中服务器域名必须使用 https 协议。

9.2 获取预置属性

在根目录的 app.js 中使用该方法

var sensors = require('./utils/sensorsdata.min.js');
sensors.getPresetProperties();

此方法可获取 SDK 版本、操作系统、操作系统版本、设备型号、网络类型、屏幕宽高、页面路径、最近一次渠道来源的相关属性。需要在获取完网络状态与设备信息、页面加载完成后调用此方法。

9.3 小程序分享的计算逻辑和规则

在 SDK 1.9版本加入了小程序的分享事件 $MPShare ,该事件在小程序中调用分享接口时触发。

$url_path 属性值会记录触发分享的页面地址。 $share_depth 属性值会记录分享的层级:A、B、C为三个不同的用户,若小程序一个页面依照 A -> B -> C 的顺序进行分享,则 A 的分享会被标记为1级分享,B 触发的分享会被标记为2级,C 则为3级分享。 其中,用户打开自己分享的页面是不会增加 $share_depth 的值。 若您希望在后续跟踪分享的效果,需要配置 allow_amend_share_path 为 true,这样神策会自动修改分享的path参数,path后面会新增参数包含distinct_id,分享次数,页面路径信息。在该分享页面被打开时,会自动解析到 $MPLaunch 和 $MPShow 中。

9.4 不覆盖 App 与 Page

SDK 1.9.5版本以后,客户可以通过配置 sensorsdata_conf.js 文件中 autoTrack:false, 使 SDK 不再覆盖小程序原生的 App 和 Page 方法。
使用该配置后,小程序 SDK 不再采集预置事件,不能使用神策提供的小程序渠道追踪。

9.5 通过 init 方法配置初始化参数

SDK 1.9.9 版本支持通过 sensors.init(para) 方法修改 sensorsdata_conf.js 中的配置参数

sensors.init({
  // 神策分析注册在 APP 全局函数中的变量名,在非 app.js 中可以通过 getApp().sensors(你这里定义的名字来使用)
  name: 'sensors',
  // 如果要通过 sdk 自动获取 openid,需要在神策分析中配置 appid 和 appsecret,并在这里标志 appid,不需要的话,不用填。
  appid: '',
  // 神策分析数据接收地址
  server_url: '数据接收地址',
  //请求发送超时时间
  send_timeout: 1000,
  // 发送事件的时间使用客户端时间还是服务端时间
  use_client_time: false,
  // 是否允许控制台打印查看埋点数据(建议开启查看)
  show_log: true,
  // 是否允许修改 onShareMessage 里 return 的 path,用来增加(用户 id,分享层级,当前的 path),在 app onshow中自动获取这些参数来查看具体分享来源,层级等
  allow_amend_share_path : true, 
  // 是否自动采集如下事件(建议开启)
  autoTrack:{  
    appLaunch:true, //是否采集 $MPLaunch 事件,true 代表开启。
    appShow:true, //是否采集 $MPShow 事件,true 代表开启。
    appHide:true, //是否采集 $MPHide 事件,true 代表开启。
    pageShow:true, //是否采集 $MPViewScreen 事件,true 代表开启。
    pageShare:true //是否采集 $MPShare 事件,true 代表开启。
  }
})

注意:
对于使用 wepy 框架开发的小程序,需要使用按照下面步骤操作
1.通过 npm i sa-sdk-miniprogram集成 SDK
2.使用wepy build --no-cache重新编译

9.6 获取 distinct_id

var sensors = require('./utils/sensorsdata.min.js'); 
sensors.init();
sensors.store.getDistinctId()

9.7 批量发送数据配置

1.可配置是否批量发送数据 batch_send:true ;默认情况下,会每隔 6s 或者每采集 6 条数据后合并发送一次;
2.可配置使用批量发送数据,且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 };
3.批量发送可能存在重复发数据的问题,因为关闭小程序的时候,我们会默认发一次数据,可能数据没返回,下次会重发,所以这个版本含有默认去重的功能,使用这个功能必须升级神策分析系统到 1.11 及以上版本,已经是 1.11 版本以上的系统也需要小版本升级;
4.批量发送中有一个优化,如果是 $MPLaunch 事件会直接发送,不会等待,因为考虑到会有较多用户打开就关闭小程序,甚至永远不来,如果使用等待 6s 的批量发送策略,会导致数据丢失,跟其他统计工具对不上。

9.8 预置事件添加自定义属性配置

1.如果是添加不需要延迟获取的属性,可以参考文档 4.2 描述的方案添加。
2.如果是需要延迟才能获取的属性,首先需要关闭 autoTrack 对应的预置事件,然后手动去发送。

  • 如果不需要我们的预置属性,可以通过 track 方法发送个对应的预置事件,加延迟的属性就可以(建议使用此方案)
  • 如果需要我们的预置属性,需要在相应的生命周期函数中调用如下方法(预置事件 $MPViewScreen 设置自定义属性不支持这种方案 )
app.js
//引入文件并完成初始化
var sensors = require('./utils/sensorsdata.min.js');
sensors.init()
App({
    onLaunch : function(options){
        // $MPLaunch 事件增加自定义属性
        sensors.quick('appLaunch', options, {
            '属性名' : '延迟获取到的属性值'
        });
    },
    onShow : function(options){
        // $MPShow 事件增加自定义属性
        sensors.quick('appShow', options, {
            '属性名' : '延迟获取到的属性值'
        });
    },
    onHide : function(){
        // $MPHide 事件增加自定义属性
        sensors.quick('appHide', {
            '属性名' : '延迟获取到的属性值'
        });
    }
});