微信小程序 SDK 标准版

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

更新日志

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

1.1 安装方法

1.1.1 下载文件

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

1.1.2 引入并配置参数

把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ; 调用 setPara() 方法设置初始化参数 注意：必须在 require() 之后，立即调用 setPara() 方法设置 小程序 app.js 的顶部引入如下代码

------app.js
    var sa = require('./utils/sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });

1.1.3 标志初始化完成

如果异步的获取 openid 等操作已经完成，此时调用 init() 方法标志已完成初始化 注意: 必须调用，否则不会发数据

------app.js
    var sa = require('./utils/sensorsdata.plugin.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });
    sa.init();

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 。

• batch_send: boolean , 小程序中是否使用批量发送数据功能,默认为 false ,配置注意事项详见常见问题 9.7 。
• datasend_timeout: number , 请求发送取消时间（请求发送后，在规定时间内未返回结果，则取消请求），默认为 1000 毫秒（1.12.9 及以上版本支持） 。

1.3 mpvue 小程序框架集成 SDK

1.3.1 集成与初始化

第一步：从 github 上下载 微信小程序 sdk ，sensorsdata.min.es6.js 第二步：将文件放到小程序项目中 第三步：在项目的 main.js 中通过 import 引入 SDK，sensorsdata.min.es6.js 必须在 vue 之前引入,然后调用 setPara() 方法设置初始化参数，调用 init() 方法完成初始化。

    import sa  from './utils/sensorsdata.min.es6.js'
    import Vue from 'vue'
    import App from './App'
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });
    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.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });
    sa.init();

2. 用户标识

相关文档链接：https://www.sensorsdata.cn/manual/user_identify.html#如何准确的标识用户

在进行任何埋点之前，都应当先确定如何标识用户。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 后再调用 sa.init() 才会发数据。 下面是常见的两种获取 openid 的初始化代码。

-------app.js  

    var sa = require('sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });
    // 如果你们能获取到openid
    sa.setOpenid(openid);
    sa.init();

-------app.js  

    var sa = require('sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址',
        appid: '在微信公众平台获取'
    });
    // 如果后端做了 appid 和 appsecret 的配置，以及 setPara() 方法中有 appid 的配置
    sa.initWithOpenid();

2.2 匿名 ID 和用户 ID 关联

默认情况下 ，SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 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();

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() 方法设置公共属性。例如：

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

4 预置事件

4.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();

4.2 预置事件设置自定义属性

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

示例：

 ------app.js
    若用户想在 $MPLaunch 事件中添加appId,query,extraData等来源相关的自定义属性，可以通过下面方法实现
    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,
                extraData:data.referrerInfo.extraData
            };
        },
        onShow: function( data ){
            //给 $MPShow 事件添加预置属性
            sa.para.autoTrack.appShow = {
                appName: '神策小程序'
            }
        },
        onHide: function(){
            //给 $MPHide 事件添加预置属性
            sa.para.autoTrack.appHide = {
                endTime: new Date()
            }
        }
    })
 -------index.js
     var app = getApp();
     Page({
        onShow: function(){
            //给 $MPViewScreen 事件添加预置属性
            app.sensors.para.autoTrack.pageShow = {
                pageName : '首页'
            }
        }
     });

注意：该代码建议嵌入到相应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	布尔类型	是否首日访问
$ip	字符串	SDK 发送数据请求携带的属性
$country	字符串	由 IP 解析得到
$province	字符串	由 IP 解析得到
$city	字符串	由 IP 解析得到
$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 支持

注意： 1.$screen_height 在 1.11.1 版本之前字段名称为‘小程序窗口高度’,取的值是小程序可使用窗口高度 2.$screen_width 在 1.11.1 版本之前字段名称为‘小程序窗口宽度’,取的值是小程序可使用窗口宽度

6.2 $MPLaunch （小程序启动）事件的预置属性：

字段名称	类型	说明	版本
$scene	字符串	启动场景	1.0以上
$url_path	字符串	页面路径
$utm_source	字符串	广告系列来源	0.9以上
$utm_medium	字符串	广告系列媒介	0.9以上
$utm_term	字符串	广告系列字词	0.9以上
$utm_content	字符串	广告系列内容	0.9以上
$utm_campaign	字符串	广告系列名称	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	字符串	广告系列来源	0.9以上
$utm_medium	字符串	广告系列媒介	0.9以上
$utm_term	字符串	广告系列字词	0.9以上
$utm_content	字符串	广告系列内容	0.9以上
$utm_campaign	字符串	广告系列名称	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	时长	1.1及以上
$url_path	字符串	页面路径	1.5及以上

6.5 $MPViewScreen （小程序页面浏览）事件的预置属性：

字段名称	类型	说明	版本
$url_path	字符串	页面路径	0.9版本之前为 $url
$referrer	字符串	前向页面地址	0.9以上
$url_query	字符串	页面参数	1.10.4以上

6.6 $MPShare （小程序分享）事件的预置属性：

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

6.7 预置的用户属性

字段名称	类型	说明	版本
$first_visit_time	Datetime	首次访问时间	1.12.9 及以上版本
$utm_source	字符串	首次广告系列来源	1.0 及以上版本
$utm_medium	字符串	首次广告系列媒介	1.0 及以上版本
$utm_term	字符串	首次广告系列字词	1.0 及以上版本
$utm_content	字符串	首次广告系列内容	1.0 及以上版本
$utm_campaign	字符串	首次广告系列名称	1.0 及以上版本

7 设置用户属性

7.1 sa.setProfile(properties)

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

• properties：object，必选。

    sa.setProfile({email:'xxx@xx'});

7.2 sa.setOnceProfile(properties)

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

• properties：object，必选。

    sa.setOnceProfile({email:'xxx@xx'});

8 实际案例使用

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

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

    // 这行是必须加入的
    var sa = require('./utils/sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });

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

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 中使用该方法

------app.js
    var sa = require('./utils/sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址',
    });
    sa.init();

------index.js
    var app = getApp();
    Page({
        onShow: function(){
            console.log(app.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 获取 distinct_id

    var sa = require('./utils/sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });
    sa.init();
    sa.store.getDistinctId()

9.5 批量发送数据配置

1.可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次； 2.可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 }; 3.使用批量发送的话，需要升级到神策1.11 以上（后端增加 _track_id 功能） 4.批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上。

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

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

• 如果不需要采集预置事件的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）

• 如果需要采集预置事件的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen $MPShare 设置自定义属性不支持这种方案 ）

------app.js
    //引入文件并完成初始化
    var sa = require('./utils/sensorsdata.min.js');
    sa.setPara({
        name: 'sensors',
        server_url: '数据接收地址'
    });
    sa.init()
    App({
        onLaunch : function(options){
            // $MPLaunch 事件增加自定义属性
            sa.quick('appLaunch', options, {
                '属性名' : '延迟获取到的属性值'
            });
        },
        onShow : function(options){
            // $MPShow 事件增加自定义属性
            sa.quick('appShow', options, {
                '属性名' : '延迟获取到的属性值'
            });
        },
        onHide : function(){
            // $MPHide 事件增加自定义属性
            sa.quick('appHide', {
                '属性名' : '延迟获取到的属性值'
            });
        }
    });