微信小程序 SDK

在微信开发者工具的本地开发环境会提示“不在以下request 合法域名列表中”，可以通过设置不校验域名来处理； 发布体验版或线上版本，需要在开发者后台将下列域名加入服务器域名中的request合法域名中
https://tsapiqa.escase.cn
https://tsapi.escase.cn

如有使用server_url，则需要将server_url的域名加到合法域名中

一、集成SDK

获取微信小程序SDK

• 点击下载
• 使用npm下载安装：npm install @ests-miniprogram-sdk/wx

1.1 原生小程序 / Taro

在小程序项目的 app.js 入口文件中通过 import 引入 SDK，配置初始化参数并调用SDK的tracking方法集成SDK

// 引入 SDK 
import ests from 'ests-sdk-wx'
// 初始化参数
const trackingConfig = {
  debug: true, // 调试模式，可打印上报的埋点数据
  server_url: '私有部署服务域名',//数据接收地址，用于私有部署服务的场景
  ts_app: '应用标识',//同项目（同一个app_key）需要区分不同的多档活动的标识
  autoTrack: {//自动采集对应生命周期的事件，默认为true:采集, false为不采集
    // appLaunch: false,//是否采集小程序首次启动事件
    // appShow: false,//是否采集小程序启动事件
  //   pageShow: false,//是否采集小程序页面浏览事件
  //   appHide: false,//是否采集小程序页面关闭/进入后台事件
  //   pageShare: false,//是否采集小程序分享事件
  },
  allow_amend_share_path: false, //是否允许修改分享链接参数，用来监测分享数据
  // channelField: "business_channel"// Tracking System渠道参数，默认获取链接的“business_channel”参数作为渠道参数
}
//调用SDK的tracking方法集成SDK 首个参数为Tracking System提供的app_key，必须
//如autoTrack.pageShow: true，调用此方法会自动采集页面浏览数据
ests.tracking('qa157646865XXX', trackingConfig)

查看更多关于pageShare(小程序分享事件)的相关信息

1.2 uni-app

在项目的 main.js 或 App.vue 中通过 import 引入 SDK，配置初始化参数并调用SDK的tracking方法集成SDK

// 引入 SDK 
import ests from 'ests-sdk-wx'
// 初始化参数
const trackingConfig = {
  debug: true, // 调试模式，可在控制台打印上报的埋点数据
  ts_app: '应用标识',//同项目（同一个app_key）需要区分不同的多档活动的标识
  autoTrack: {//自动采集对应生命周期的事件，默认为true:采集, false为不采集
    // appLaunch: false,//是否采集小程序首次启动事件
    // appShow: false,//是否采集小程序启动事件
    // pageShow: false,//是否采集小程序页面浏览事件
    // appHide: false,//是否采集小程序页面关闭/进入后台事件
    // pageShare: false,//是否采集小程序分享事件
  },
  allow_amend_share_path: false, //是否允许修改分享链接参数，用来监测分享数据
  // channelField: "business_channel"// Tracking System渠道参数，默认获取链接的“business_channel”参数作为渠道参数
}
//调用SDK的tracking方法集成SDK 首个参数为Tracking System提供的app_key，必须
//如autoTrack.pageShow: true，调用此方法会自动采集页面浏览数据
ests.tracking('qa157646865XXX', trackingConfig)

1.3 微信小程序插件

微信小程序SDK在V2.1.8后支持微信小程序插件的埋点监测，用法与小程序基本一致。 不同之处在于插件中无法调用getApp().ests方法来获取SDK对象，所以需要在埋点的插件页面都引入一次SDK。

1.3.1 在存放SDK的目录下新建一个index.js，在index.js中引入并初始化SDK

// 引入 SDK 
import ests from 'ests-sdk-wx'

// 初始化参数
const trackingConfig = {
  debug: true, // 调试模式，可在控制台打印上报的埋点数据
  ts_app: '应用标识',//同项目（同一个app_key）需要区分不同的多档活动的标识
  autoTrack: {//自动采集对应生命周期的事件，默认为true:采集, false为不采集
    // appLaunch: false,//是否采集小程序首次启动事件
    // appShow: false,//是否采集小程序启动事件
    // pageShow: false,//是否采集小程序页面浏览事件
    // appHide: false,//是否采集小程序页面关闭/进入后台事件
    // pageShare: false,//是否采集小程序分享事件
  },
  allow_amend_share_path: false, //是否允许修改分享链接参数，用来监测分享数据
  // channelField: "business_channel"// Tracking System渠道参数，默认获取链接的“business_channel”参数作为渠道参数
}
//调用SDK的tracking方法集成SDK 首个参数为Tracking System提供的app_key，必须
//如autoTrack.pageShow: true，调用此方法会自动采集页面浏览数据
ests.tracking('qa157646865XXX', trackingConfig)

//导出SDK对象
export default ests

1.3.2 导出SDK对象后，在需要埋点的页面都引入集成了SDK的index.js，否则无法调用SDK的event方法

// plugin/pages/index.js
import ests from '../../sdk/index'

`

二、设置应用全局自定义属性

接口参数类型：JsonObject
当需求整个小程序范围内访问数据都携带一些业务自定参数的时候，可以调用setTsExt方法进行设置

示例

//设置全局自定义扩展属性 可选
getApp().ests.setTsExt({
    appId: "小程序ID",
    appName: "小程序名称"
})

三、设置用户属性

在登录成功后调用ests.setUserInfo()设置用户属性，且应该在发送页面采集数据请求ests.pageview()前调用，否则数据上无法准确识别用户， 如果没有用户信息，可以不用设置，SDK会给用户自动分配一个device_id，可在调试模的控制台日志中看到该属性

参数说明：JsonObject，只支持以下属性的设置

示例

//在app.js中的获取用户信息成功回调函数里设置用户信息
success: res => {
  var userInfo = res.userInfo
 getApp().ests.setUserInfo({ 
    guid: "xxx",//用户唯一标识，可用业务系统自己的用户ID；如果微信环境可以用open_id作为guid来标识用户；可选
    open_id: "otzXTjovtYkMOx56Phy764-XXXXX",//用于微信环境下open_id的获取；如果没有，可以不设置；可选
    union_id: "oDSWq1S0lPkZk0SVL2K_2JmpdXXX"//用于微信环境下的union_id获取；如果没有，可以不设置；可选
 })   
}

四、上报用户页面浏览行为(PV&UV)

• 在设置完用户信息后，可在pageShow生命周期中设置自定义页面名称、页面标题等（否则SDK会默认获取页面的title标签的内容作为页面名称与页面标题）；
• 若SDK初始化配置时并未设置pageShow:true，可手动上报用户页面浏览行为(PV&UV)

示例

 //注意：如果是插件的埋点，无法通过getApp()的方式来获取ests，参考 1.4 微信小程序插件 说明
  var app = getApp() 
  //设置页面名称 可选
  app.ests.setPageName('自定义页面名称')
  //设置页面标题 可选
  app.ests.setPageTitle('自定义页面标题')

  //手动上报用户页面浏览行为(PV&UV) 可选，如开启了页面自动采集事件（pageShow:true），则不能调用该方法，否则会出现重复的PV数据
  // app.ests.pageview()

至此已完成对页面数据的采集，用户访问页面，即可监测到对应数据

五、自定义事件埋码

SDK 初始化后，通过 event 方法自定义事件跟踪用户行为，并为事件添加自定义事件属性

接口参数类型：JsonObject
JsonObject中的每个参数如下

• event_name：String 事件名称，必须
• event_param：JsonObject 事件属性，非必须

示例 1：查看商品，加入购物车流程

// 在进入商品详情页面加载完成后埋点上传「商品详情」事件
//获取app实例
//注意：如果是插件的埋点，无法通过getApp()的方式来获取ests，详情参考 1.4 微信小程序插件 说明
var app = getApp()

var eventInfo = {
  //定义事件名称
  event_name: "商品详情",
  // 定义事件属性
  event_param: {
    "productId": "1",
    "productName": "源慧大礼品",
    "productCategory": "电子",
  }
}
//调用采集事件接口
app.ests.event(eventInfo);



// 在商品详情页面为加入购物车按钮进行埋点上传，事件为「加入购物车」
var eventInfo = {
  //定义事件名称
  event_name: "加入购物车",
  // 定义事件属性
  event_param: {
    "productId": "1",
    "productName": "源慧大礼品",
    "productCategory": "电子",
  }
}
//调用采集事件接口
app.ests.event(eventInfo);

示例 2：用户登录流程

// 点击登录按钮后未提交登录请求前进行埋点上传，事件为「登录」，该事件属性为空
//获取app实例
//注意：如果是插件的埋点，无法通过getApp()的方式来获取ests，详情参考 1.4 微信小程序插件 说明
var app = getApp()

var eventInfo = {
  //定义事件名称
  event_name: "登录"
}
//调用采集事件接口
app.ests.event(eventInfo);


// 点击登录按钮提交登录请求后进行埋点上传，事件为「登录成功」
var eventInfo = {
    //定义事件名称
    event_name: "登录成功",
    // 定义事件属性
    event_param: {
      "status": "success",// 设置登录状态 success/fail
      "errMsg": ""// 设置登录失败错误信息
    }
}
//调用采集事件接口
app.ests.event(eventInfo);

通过上面的示例，可以在任意流程进行事件埋点。

数据校验指引