JS探针采集

1 SDK引入

SDK共有两种方式引入，分别为 npm模块方式，以及普通的 script 标签引入。

1.1 script方式(支持https)

<!-- 核心引入 -->
<script src="https://g.alicdn.com/woodpeckerx/jssdk/wpkReporter.js" crossorigin="true"></script>
<!-- 插件引入 -->
<script src="https://g.alicdn.com/woodpeckerx/jssdk/plugins/globalerror.js" crossorigin="true"></script>
<!-- combo方式 -->
<script src="https://g.alicdn.com/woodpeckerx/jssdk??wpkReporter.js,plugins/globalerror.js" crossorigin="true"></script>

1.2 script方式快捷引入

<!-- 快捷引入(探针)：导入+自动初始化 -->
<!-- 注意：引入这段脚本后将启用SDK所有的上报功能，建议阅读完文档再决定是否直接引用 -->
<script>
!(function(c,i,e,b){var h=i.createElement("script");var f=i.getElementsByTagName("script")[0];h.type="text/javascript";h.crossorigin=true;h.onload=function(){c[b]||(c[b]=new c.wpkReporter({bid:"wpktest"}));c[b].installAll()};f.parentNode.insertBefore(h,f);h.src=e})(window,document,"https://g.alicdn.com/woodpeckerx/jssdk/wpkReporter.js","__wpk");
</script>

1.3 npm模块方式

1. 安装依赖
npm i wpk-reporter --save
 
2. 引入核心
import wpkReporter from 'wpk-reporter'
 
3. 引入插件
import wpkinterfacePlugin from 'wpk-reporter/dist/plugins/interface'

2 上报

2.1 demo预览

const wpk = new wpkReporter({
  bid: 'wpk新建应用后分配',
  rel: '', // 支持函数，需返回最终的版本字符串'
  uid: '', // 支持函数，需返回最终的uid字符串
  plugins: [], // 可选
  spa: false   // 如果你的应用是spa，那就大胆的设为true吧，默认false
})
wpk.install() // 初始化！一定记得调用
// 现在，试一下主动上报一条日志
wpk.report({
  category: 100, // 必填，一般是100以上的数字，1~99为预留为系统使用
  msg: 'hello wpk'
})

2.2 配置参数

• bid 必填

啄木鸟平台应用标识，新建后分配

• rel 可选，推荐设置

前端资源版本号，强烈推荐设置支持字符串以及函数两种方式设置，函数最终需要返回一个字符串

• uid 可选，推荐设置

浏览当前页面的用户唯一标识，强烈推荐设置，默认为 uuid支持字符串以及函数两种方式设置，函数最终需要返回一个字符串

• plugins 可选

需要开启的插件没有设置任何插件时，默认加载 wpkflowPlugin 用于上报站点流量数据

• sampleRate 可选

采样率，大业务（日志量大于 xxx / 天）推荐设置默认规则，除了 性能数据的采样率为 10%，其余类型的日志均为 100%

• beforeSend 可选

参数为完整的 logData对象日志上报的前置处理，返回 false可阻止日志上报，否则返回true（记得一定要返回）

• spa 可选

是否spa应用，默认 false设为 true后，可配合 wpkflowPlugin更好的打点（自动监听hashchange）

• debug 可选

开启debug模式，默认 false开启后，将会有更详细的打点过程日志输出，一般用于接入时联调分析，生产环境不建议打开

• ignoreScriptError 可选

是否忽略 'Script Error'即第三方脚本错误，默认为 true

• onlyCustom 可选（同时接入内核高可用的业务需关注）

是否关闭静默上报(插件提供的功能)，只保留自定义上报功能，默认为 false用途：用于规避内核上报的数据与jssdk的数据出现重复，同时也浪费流量，普通业务无需关注

3 插件

sdk核心默认只包含自定义打点，业务可按需添加插件，扩展sdk的打点能力。

3.1 使用方式

3.1.1 构造方法传参

import wpkinterfacePlugin from 'wpk-reporter/dist/plugins/interface'
const wpk = new wpkReporter({
  // ...
  plugins: [[
    wpkinterfacePlugin, { sampleRate: 0.5 }
  ]],
  // ...
})
// 如果是script方式引入插件，也可以直接使用 wpkinterfacePlugin变量

3.1.2 接口方式

// 确保已经引入
import wpkinterfacePlugin from 'wpk-reporter/dist/plugins/interface'
// ... ...
wpk.addPlugin(interfacePlugin, { sampleRate: 0.5 })

3.2 插件列表

• 3.2.1 wpkglobalerrorPlugin (含 jserror resourceError) - 全局错误监控

参数：opts

{
  jsErr: true, // 是否开启js error监控
  jsErrSampleRate: 1, // js error采样率，默认为 1
  jsErrFilter: fn, // js error过滤回调函数，参数为 error对象，返回 false则不上报
  resErr: false, // 是否开启资源加载异常监控
  resErrSampleRate: 1 // 资源异常监控采样率，默认为 1
  resErrFilter: fn // 资源加载异常过滤的回调函数，参数为 error对象，返回 false则不上报
}

默认只会捕获 js error(包括unhandledrejection)，需要监控资源加载异常可以设置 resErr: true

• 3.2.2 wpkinterfacePlugin - 接口异常监控

参数： opts

{
  enable: true, // 默认为 true，可设为false关闭插件功能
  sampleRate: 1,  // 采样率，默认为 1
  withBody: false, // 是否上报请求的body参数，默认 false
  errorFilter: function(params) {
    // 异常过滤回调函数，参数包含 请求地址、响应码及响应内容，返回 false则不上报
    // params格式为 {url: '', status: '', response: '', body: '', reqHeaders: {}, resHeaders:{},queryString: ''}
    // 业务可返回 {bizCode: '', msg: '', traceId: ''}，sdk会将他们一并上报
 }
}

默认自动上报所有基于 xhr或 fetch的异步请求，有特殊情况的可通过 errorFilter自定义

Set Access-Control-Allow-Headers when allowing headers to be passed from the client to the server (e.g. If-Match). Set Access-Control-Expose-Headers when allowing headers to be passed back from the server to the client (e.g. ETag)

3.2.3 wpkperformancePlugin - 基础性能数据自动上报

参数: opts

{
  enable: true, // 默认为 true，可设为false关闭上报
  sampleRate: 0.1 // 采样率，默认 100%
}

3.2.4 wpkflowPlugin - 站点流量监控参数：opts，{ spa: false  }

参数：opts，{ enable: true // 默认开启 } 默认在 onload时会自动上报在sdk构造参数中设置 spa: true，则在hashchange的时候也会自动上报

4 API

说明

• 每条上报的数据 logData，我们称之为一条日志数据，类型为 Object
• logData的属性包含SDK所有构造参数，除此之外，还可以包含以下属性：

构造参数为全局，logData参数则为单次有效，即只影响单次的上报

category 日志监控分类（比如 性能、接口、js错误等）1 ~ 99为系统保留，自定义监控项由100开始，已分配的值：1 js错误，2 api，3 首屏性能，4 资源加载错误，5 页面访问，6 白屏, 7 harlog

msg 日志描述信息c1 自定义字段1c2 自定义字段2c3 自定义字段3c4 自定义字段4c5 自定义字段5

• 所有api均返回当前sdk实例，因此你可以方便的进行链式调用

.report(logData)

主动上报一条日志，日志内容为 logData

.reportFlow(logData)

主动上报一次访问的打点，logData参数可选，需要额外参数时可赋值

.reportError(error, logData)

主动上报一个jserr类型的打点，额外参数可在 logData中设置

.reportApiError(data)

主动上报接口异常日志，data为一个Object类型的参数，字段包含

{
  msg: '',
  url: '',
  method: '',
  queryString: '',
  body: '',
  response: '',
  status: '',
  spent: ''
  c1: '', c2: '', c3: '', c4: '', c5: ''
}

.setConfig(opts)

更新sdk实例配置

.install()

sdk安装，即初始化所有的设置，包含各个插件的初始化(在plugins参数中指定)等调用此方法后，sdk的初始化工作才算完成，下面才能成功调用其他API

.installAll()

sdk安装，初始化所有的设置，包含内置的所有插件，及安装全家桶，适合不接内核的场景

.diagnose()

诊断函数，方便调试调用后会在浏览器控制台输出诊断信息，并重定向到一个新页面，显示上报结果