微信小程序 SDK 使用说明

最后更新于：2018-08-14 15:15:02

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

更新日志

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

1.1 下载 sdk

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

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

var sensors = require('./utils/sensorsdata.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 和 appsercret ，同时在这里指定 appid 。

• server_url: 数据接收地址, 如果你使用的是 cloud 云版环境，地址类似于 http://xq_zgq.cloud.sensorsdata.cn/sa?project=gxq&token=251d0b0。 注意: 请在微信开发设置，服务器域名的 request 合法域名内，把这个地址加上（如果数据接收地址有端口号的话，参考本页第九点常见问题）。

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

• max_string_length: 字符串最大长度，防止属性中误传了特别长的字符串，导致请求失败等异常。

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

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

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

1.3 mpvue 小程序框架集成 SDK

1.3.1 集成与初始化

第一步：从 github 上下载 微信小程序 sdk ，sensorsdata.js 和 sensorsdata_conf.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.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 ，我们暂时称这个为 open_id
3. 数据库中保存的，用户真实 id 。我们暂时称为 user_id

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

2.1 操作暂存和 sa.init 表示准备完成

因为获取 openid 是一个异步的操作，但是冷启动事件等会先发生，这时候这个冷启动事件的 distinct_id 就不对了。
所以我们会把先发生的操作，暂存起来，等获取到 openid 等后调用 sa.init() 后才会发数据。 下面是常见的两种获取 openid 的初始化代码。

-------app.js  

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

-------app.js  

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

-------app.js  

var sensors = require('sensorsdata.js');
// 如果能获取到 userid 不使用openid
sensors.login(userid);
sensors.init();

3. 自定义事件追踪

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

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

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

事件公共属性：可以在小程序页面 Page() 执行前使用 registerApp() 方法注册事件公共属性，这样在后续的所以事件都会添加这些公共属性。例如：

    // 注册事件公共属性。  
    var app = getApp();
    app.sensors.registerApp({
        userLever: 'VIP3'，
        userSex: '男'
    });

4 预置事件

4.1 预置事件追踪

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

例如：在 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.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.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 相关属性

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

5.2 $latest_utm 相关属性

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

5.3 首次 utm 的相关属性

在小程序 sdk 发现设备之前没有加载过 sdk ，且如果冷启动 app_launch 能解析到 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 所有事件都会有的预置属性：

注意： $latest_utm 相关参数只有在冷启动或热启动事件中能取到 utm 相关值，才会重置

6.2 除 6.1 之外 $MPLaunch 事件会有的预置属性：

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

6.3 除 6.1 之外 $MPShow 事件会有的预置属性：

6.4 除 6.1 之外 $MPHide 事件会有的预置属性：

6.5 除 6.1 之外 $MPViewScreen 事件会有的预置属性：

6.6 除 6.1 之外 $MPShare 事件会有的预置属性：

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.js 和 sensorsdata_conf.js 放在根目录 untils 目录下

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

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

App({
  onLaunch: function () {
          // 如果获取到用户的真实id信息
          sensors.login(user_id);
          // 如果获取到了用户的信息,可以给这个用户设置 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 小程序中服务器域名设置不能有端口号

在 2018-4-9 前，神策默认提供的服务器地址是带端口号的，而小程序中服务器域名设置不能带端口号。
现在 2018-4-9 后的云版环境（使用我们提供的 cloud 环境），可以使用这个地址来解决 https://xxx.datasink.sensorsdata.cn/（也就是在你们神策地址的基础上，中间加了datasink）
私有部署的环境，因为本身需要你们配置，跟云版不同

9.2 获取预置属性

sa.getPresetProperties();

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

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

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

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