如何接入小程序监控SDK

1. 支持情况

• [√] 支付宝小程序
• [√] 微信小程序
• [√] 钉钉小程序（内置于 APPX中，用户只需在开放平台接入稳定性监控即可，不需要再引入SDK）
• [√] 百度智能小程序
• [√] 头条小程序

2. 设置安全域名

在小程序开发者后台，将 https://px.effirst.com 添加到 Request 合法域名
务必设置安全域名、设置安全域名、设置安全域名，重要的事情讲三遍，否则所有数据无法上报！！！

3. 引用方式

3.1 npm包（推荐）

// 1. 安装依赖
npm i miniapp-reporter --save

// 2. 引入，目前支持 支付宝小程序(alipay)、微信小程序(wechat)、钉钉小程序(dd)、百度小程序(baidu)、头条小程序(tt)
import AliPayReporter from 'miniapp-reporter/alipay'
import WechatReporter from 'miniapp-reporter/wechat'
import DDReporter from 'miniapp-reporter/dingtalk'
import BaiduReporter from 'miniapp-reporter/baidu'
import TTReporter from 'miniapp-reporter/tt'

3.2 源码依赖

目前大部分小程序都已经支持 npm了，所以首推 npm依赖的方式来使用SDK
当然，有些平台对npm的支持略显特殊，如果发现安装依赖后无法编译，那么可以尝试用源码依赖的方式来解决

// 如何获取代码 
// 1. 从 node_modules/miniapp_reporter 目录下拷贝代码到小程序的项目目录下
// 或 2. 从 cdn上下载：地址待公布

举栗：微信小程序项目 wechatDemo 源码依赖SDK
1. 获取代码 wechat.js
2. 拷贝 wechat.js 至项目目录中，比如 wechatDemo/utils
|- wechatDemo
|----utils
|------wechat.js

注：SDK的构建产物支持直接用ES6语法来 import，也可以 require

4 如何使用

4.1 创建应用

登录 https://yueying.effirst.com/#/app/add?type=mapp 选择小程序类型、应用名称、及应用描述，之后点击创建应用即可

4.2 初始化

一般情况下，我们初始化一次SDK即可，可以把SDK实例导出供全局复用

1. 确保已按照「步骤3：引用方式」正确安装依赖（这里以 npm依赖为例）2. 在 utils目录下，新增 miniapp-reporter.js 文件，文件加入以下内容

// miniapp-reporter.js

import MiniAppReporter from 'miniapp-reporter/alipay'
const itraceInstance = MiniAppReporter.getInstance({
  bid: 'your bid', // 应用标识，必填，从「步骤4.1：创建应用」获取
  uid: '', // 用户标识，非必须，默认是 uuid，建议设置；支持函数
  rel: ''  // 小程序版本，非必须，默认为空，建议设置；支持函数
//  rel: function () { xxxx }
})

// 导出单例
export default itraceInstance

注：微信小程序，只需要将导入的包换为wechat即可：'miniapp-reporter/wechat'

4.3 全局监听

全局监听主要是针对 app.js，这一步可以实现对 **全局异常 **以及 **API请求 **的监控

// 根目录下的 app.js

import itrace from '/utils/miniapp-reporter';

App(
  itrace.wrapApp({   
    onLaunch () {},
    onShow () {},
    onHide () {},
    onError (error) {}
  })
);

// itrace.wrapApp 的参数与原App的参数保持一致
// 因此，这一步变动，仅仅只把原来App的入参用 itrace.wrapApp() 来包裹一层，使用成本较低

4.4 页面监听

目前主要是监听页面PV

// 某页面的入口js

import itrace from '/utils/miniapp-reporter';

const app = getApp();

Page(
  itrace.wrapPage({
    data: {},
    onLoad() {},
    onShow() {},
    onHide () {},
    onUnload () {},
    onReady () {} , 
    onTodoChanged(e) {},
    addTodo() {}
  })
);

// 显然，这里的调用方式跟 app.js是一样的

5 进阶

5.1 手动上报

除了常规的 PV/UV、JSError、API请求监控之外，我们还提供了强大的自定义上报功能 结合iTrace Web平台的聚合分析功能，用户可以轻易做到对各种场景的监控分析

// 前置条件，引入 itrace实例
// 任意页面的 JS
import itrace from '/utils/miniapp-reporter';

5.1.1 通用的手动上报接口 report

// logData为一个Object类型的参数
itrace.report(logData)

• logData的通用字段：

{
	category: 100, // [必须] 指定监控项，0-99 为系统预留
  msg: '',       // [必须] 一段自定义的字符串
  c1: '',        // [必须] 预留的扩展字段1，即上报的日志可以带上该属性用于聚合分析；下同
  c2: '',        // [必须] 预留的扩展字段2
  c3: '',        // [必须] 预留的扩展字段3
  c4: '',        // [必须] 预留的扩展字段4
  c5: '',        // [必须] 预留的扩展字段5
 	w_succ: 1,     // [可选] 用于计算率的标识,可选为 1 和 0
  wl_avgv1: 100, // [可选] 用于监控如耗时，性能等均值，必须是一个数字
}

5.1.2 SDK内置的 API

* 手动上报 JS异常 reportJSError

itrace.reportJSError(error, logData) // 等价于 itrace.reportError

参数说明

• error 必须是一个标准的 JS Error对象：https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Error 
• **logData **参数格式参考 4.1.1章节的 logData通用字段（category不需要传！category不需要传！）

* 手动上报 api数据

itrace.reportApi(logData) // 等价于 itrace.reportApiError

**logData字段如下：

{
  url: '',         // 建议是完整请求地址，包括协议, https://your.gateway.domain/api/user
  method: '',      // HTTP请求方法，GET、POST、PUT、DELETE等
  queryString: '', // 支持字符串或者 Object格式：p1=v1&p2=v2 or { p1: v1, p2: v2 }
  headers: {},     // 请求头，Object格式
  body: '',        // 请求内容
  response: '',    // 响应内容
  respHeaders: {}, // 响应头
  status: 200,     // HTTP响应码
  spent: 100       // 请求RT：整数，默认单位毫秒
}

5.2 其他

能阅读到此处的用户，说明默认的 SDK配置已经无法满足你了。实际上，这一小节的内容正是介绍 SDK的各种灵活配置的。

5.2.1 采样率设置

日志量较大的情况下，建议配置一定采样率，避免日志全量上报

// 1. 全局，默认采样率是 1(100%)
const itraceInstance = MiniAppReporter.getInstance({
//  ...
  sampleRate: 0.5 // 或者 50%，所有日志类型都会应用此采样率
//  ...
})

// 2.单独对 JSError进行采样
const itraceInstance = MiniAppReporter.getInstance({
//  ...
  jsErrorSampleRate: 0.5 // 或者 50%，JS异常日志都会应用此采样率
//  ...
})

// 3.单独对 api进行采样
const itraceInstance = MiniAppReporter.getInstance({
//  ...
  apiSampleRate: 0.5 // 或者 50%，api请求日志都会应用此采样率
//  ...
})
// 4.单独对 性能 进行采样
const itraceInstance = MiniAppReporter.getInstance({
//  ...
  launchPerfSampleRate: 0.5, // 或者 50%，启动性能日志都会应用此采样率
  pagePerfSampleRate: 0.5 // 或者 50%，页面性能日志都会应用此采样率
//  ...
})

5.2.2 全局日志过滤

所有日志上报时都会应用此过滤器

const itraceInstance = MiniAppReporter.getInstance({
//  ...
  beforeSend: function (logData) {
  	// logData格式参考 4.1.1章节
    // 有需要的用户，在这里可以对 logData进行加工
    
    // 如果要阻止本条日志上报，可以
    // return false
  }
//  ...
})

5.2.3 JSError过滤

可能在部分场景下，我们并不关注某些类型的JS异常，此时就可以使用该过滤器

const itraceInstance = MiniAppReporter.getInstance({
//  ...
  jsErrorFilter: function (error) {
  	// error为一个标准的 JS Error对象
    
    // 如果要阻止本条日志上报，可以
    // return false
  }
//  ...
})

5.2.4 API相关

SDK 默认会开启 API监控的功能，同时由于安全方面的考虑，SDK默认并不会上报请求体、请求头、响应体以及响应头，但这些默认行为，你都有机会来自定义

const itraceInstance = MiniAppReporter.getInstance({
//  ...
  disableApi: true,         // 关闭 api监控
  apiBody: false,           // 上报请求体，默认 false，不上报
  apiResponse: false,       // 上报响应体，默认 false，不上报
  apiRequestHeader: false,  // 上报请求头，默认 false，不上报
  apiResponseHeader: false, // 上报响应头，默认 false，不上报
  apiFilter: function (logData) {
	// ...
  	// logData的格式参考 「手动上报 api数据」小节
    // return false 可阻止本条日志上报
  // ...
	}
//  ...
})

5.2.5 性能相关

配置

const itraceInstance = MiniAppReporter.getInstance({
//  ...
  launchPerfSampleRate: 0.5, // 或者 50%，启动性能日志都会应用此采样率
  pagePerfSampleRate: 0.5, // 或者 50%，页面性能日志都会应用此采样率
  disableLaunchPerf: true,// 关闭 启动性能 监控
  disablePagePerf: true,// 关闭 页面性能 监控
  //性能日志默认将在 onReady 钩子回调 5000ms后或onHide/onUnload钩子回调时上报
  perfUploadAfter: 5000,
  launchPerfFilter: function (logData) {
	// ...
    // return false 可阻止本条日志上报
  // ...
	}
  pagePerfFilter: function (logData) {
		// return false 可阻止本条日志上报
	}
//  ...
})

性能标记

itrace.perfMark(name, type)

• type：
  • start: 表示标记指标的起始时间点
  • end: 表示标记指标的结束时间点
• name:
  • bizAvailable： 业务可用
  • wl_avgv1 - wl_avgv5: 自定义指标
• demo

setData({...}, function () {
  itrace.perfMark('bizAvailable', 'end')// 设置业务可用结束时间点
})

itrace.perfMark('wl_avgv1', 'start')// 设置性能指标1的时间起点
// 指标1相关代码执行开始
...
// 指标1相关代码执行结束
itrace.perfMark('wl_avgv1', 'end')

6 附录

6.1 完整 Demo可参考: 待补充