岳鹰全景监控

# 探针API使用进阶

本文将会进一步为你讲解探针构造函数配置、设置插件、如忽略部分JS异常、设置用户id等。


# 1、探针配置


在《快速接入》一文中已经讲到了如何初始化探针，而初始化探针时可通过构造方法传入Object类型的配置参数。本文将深入讲解配置参数。


# 1.1、 探针配置demo


创建探针实例代码示例。


// 1、 构造方法参数设置配置
const __wpk = new wpkReporter({
 bid: '应用唯一标识',
 rel: '', // 支持函数，需返回最终的版本字符串'
 uid: '', // 支持函数，需返回最终的uid字符串
 plugins: [], // 可选
 spa: false   // 如果你的应用是spa，那就大胆的设为true吧，默认false
})
__wpk.install()
// or 
// 2、通过api设置配置
__wpk.setConfig({
   uid: 'testid',
 ...
})


# 1.2、配置参数说明


# bid

  • 类型：String
  • 必填：是
  • 默认值：无
  • 描述：平台分配的应用唯一标识，在创建应用时自动分配的 <code>应用标识</code> 字段


# rel

  • 类型：String,Function
  • 必填：否
  • 默认值：无
  • 注意事项：若设置为Function，则终需要返回一个字符串
  • 描述：前端版本号，推荐设置，设置后，可在平台进行版本对比等操作
  • 示例代码


new wpkReporter({
 bid: '应用唯一标识',
 rel: '2.2.1'
})
// or 
new wpkReporter({
   bid: '应用唯一标识',
 rel: function () {
   // 自实现rel获取逻辑
   return rel
 }
})


# uid

  • 类型：String,Function
  • 必填：否
  • 默认值：uuid
  • 注意事项：若设置为Function，则终需要返回一个字符串
  • 描述：浏览当前页面的用户唯一标识，推荐设置
  • 示例代码


new wpkReporter({
 bid: '应用唯一标识',
 uid: 'useridStr'
})
// or 
new wpkReporter({
   bid: '应用唯一标识',
 uid: function () {
   // 自实现uid逻辑
   return uid
 }
})


# plugins

  • 类型：Array (二维数组）
  • 必填：否
  • 默认值：wpkflowPlugin 或 所有插件
  • 注意事项：若未设置此项。使用install() 安装时，默认wpkflowPlugin。使用installAll() 安装时，默认所有插件
  • 描述：需要开启的插件
  • 示例代码: (更多插件，详见插件配置）


const __wpk = new wpkReporter({
 bid: '应用唯一标识',
 rel: '', // 支持函数，需返回最终的版本字符串'
 uid: '', // 支持函数，需返回最终的uid字符串
 plugins: [
   [
     wpkglobalerrorPlugin,
     {
       resErr: false,
       jsErr: true
     }
   ]
 ], // 可选
 spa: false   // 如果你的应用是spa，那就大胆的设为true吧，默认false
})


# sampleRate

  • 类型：Number
  • 必填：否
  • 默认值：1
  • 注意事项：0~1之间的任何数字
  • 描述：采样率


# spa

  • 类型：Boolean
  • 必填：否
  • 默认值：false
  • 描述：是否为单页面应用，针对单页面应用开启此选项后，可更准确地采集PV


# debug

  • 类型：Boolean
  • 必填：否
  • 默认值：false
  • 注意事项：生产环境不要开启此项
  • 描述：是否开启debug模式，开启后，将会有更详细的打点过程日志输出，一般用于接入时验证


# cluster

  • 类型：String
  • 必填：否
  • 默认值：'cn'
  • 注意事项：可选值： 'cn'：国内集群；'intl': 国际集群。请注意<code>cluster配置</code>必须与使用平台相匹配


# ignoreScriptError

  • 类型：Boolean
  • 必填：否
  • 默认值：true
  • 描述：是否忽略 JS 异常中的  <code>Scrpit error</code> 错误


# beforeSend

  • 类型：Function
  • 必填：否
  • 默认值：无
  • 描述：日志上报的前置处理，返回 false可阻止日志上报
  • 示例代码


new wpkReporter({
 bid: '应用唯一标识',
 beforeSend: function(logData) {
   // 根据自身业务和数据，判断是否要上报
   return true
 }
})



# 2、插件化配置及使用

如果你需要一些更深入，更高端的玩法，那么本主题你将会带你走上高玩之路。


# 2.1、接入

我们先忘记之前的快速接入，从0开始来。


# 2.1.1、基础引入和初始化



 <!--引入探针核心 -->
 <script src="https://g.alicdn.com/woodpeckerx/jssdk??wpkReporter.js" crossorigin="true"></script>
 <script>
 (function(){
     var reporter = new wpkReporter({
       bid: '',
       rel: '0.0.0', // 支持函数，需返回最终的版本字符串'
       uid: 'xxx', // 支持函数，需返回最终的uid字符串
       plugins: [], 
       spa: false   // 如果你的应用是spa，那就大胆的设为true吧，默认false
     })
     reporter.install()
     window.__wpk = reporter
  })(window)
 </script>


此时，我们引入了探针的核心，同时获得了PV打点及主动上报数据的功能（JS异常、资源异常、页面性能啥的都没有了）。


# 2.1.2、尝试添插件


以globalerror插件为例。


 <!--引入探针和一个插件 -->
 <script src="https://g.alicdn.com/woodpeckerx/jssdk??wpkReporter.js,plugins/globalerror.js" crossorigin="true"></script>
 <script>
 (function(){
     var reporter = new wpkReporter({
       bid: '',
       rel: '0.0.0', // 支持函数，需返回最终的版本字符串'
       uid: 'xxx', // 支持函数，需返回最终的uid字符串
       plugins: [
           [
           wpkglobalerrorPlugin, // 插件名
           { // 配置参数
               resErr: true, // 你获得了资源异常监控技能
             resErrFilter: function(event) {
               // 根据你自身的需求决定是否上报
               return true // 返回true，则上报日志，返回false，丢弃日志
             },
             jsErr: true, //你获得了JS异常监控技能
             jsErrFilter: function(event) {
               // 根据你自身业务需要进行过滤
               return true // 返回true，则上报日志，返回false，丢弃日志
             }
           }
         ]
       ], 
       spa: false   // 如果你的应用是spa，那就大胆的设为true吧，默认false
     })
     reporter.install()
     window.__wpk = reporter
  })(window)
 </script>


PS：请认真关注 <code>探针引入</code> 及 <code>插件(plugins)</code> 的变化，你就明白了如何增加一个插件了



# 2.2、插件列表


# JS&资源异常插件

  • 插件名：wpkglobalerrorPlugin
  • 引入路径：plugins/globalerror.js
  • 包含功能：JS异常，资源加载异常监控
  • 配置参数


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

# API监控插件

  • 插件名：wpkinterfacePlugin
  • 引入路径：plugins/interface.js
  • 包含功能：API监控 （只支持基于 XMLHttpRequest 和 Fetch）
  • 配置参数


{
 enable: true, // 默认为 true，可设为false关闭插件功能
   sampleRate: 1, // 采样率，默认为 1
   withBody: false, // 是否上报请求的body参数，可能涉及敏感信息，故默认 false
 withResp: false, // 上报日志是否包含api返回数据，可能涉及敏感信息，故默认 false
   errorFilter: function(params) {
  /* params 格式
   {
     url: '', // api url，
     status: 200, // http status
     response: '' // API请求的body内容
     // 详细可参考 
     // https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/response
     // https://developer.mozilla.org/zh-CN/docs/Web/API/Response
   }
   */
   // 返回值可以是 false 或者 Object 对象。返回false 则此次api数据直接丢弃
   return customParams
}
}


  • errorFilter 返回数据

若需要在此时对API上报数据进行自定义或阻止符合特定条件的数据上报时，customParams的定义就非常有用且重要，返回参数如下。


// customParams 可选如下
false // 阻止本次数据上报

// or Object
{
 bizCode: 404, // 对标http status。当你的接口 http status都是 200，通过内部错误码标识时，可设置次值
 msg: 'err' // api错误信息。若要上报此字段。配置参数中withResp必须设置为true，
}


# 性能监控插件

  • 插件名：wpkperformancePlugin
  • 引入路径：plugins/performance.js
  • 包含功能：页面性能监控
  • 配置参数
{
   enable: true, // 默认为 true，可设为false关闭上报
  sampleRate: 1 // 采样率，默认 100%
}



← bid(应用标识)的作用 →