# 探针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
  • 必填:是
  • 默认值:无
  • 描述:平台分配的应用唯一标识,在创建应用时自动分配的 应用标识 字段


# 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': 国际集群。请注意cluster配置必须与使用平台相匹配


# ignoreScriptError

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


# 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:请认真关注 探针引入插件(plugins) 的变化,你就明白了如何增加一个插件了



# 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%
}