# 探针API使用入门


# 1、探针接入方式



# 1.1 cdn方式接入(快捷接入)


请按照以下步骤和图例说明接入探针。

  1. 在平台创建HTML5应用后,选择<script>标签引入接入方式。
  2. 点击复制代码并粘贴到 </head>节点。


# 注意事项


  • 在head内初始化能更早发现初始化前的问题。也可以放到body内,但必须保证在onLoad之前初始化,否则会丢失PV和页面性能数据。
  • 使用amd加载器(如requirejs)的页面不能直接使用这段脚本。




# 1.2 npm方式接入


请按照以下步骤和图例说明接入探针。


  1. 在平台创建 HTML5 应用后,选择 npm 接入方式。
  2. 按照平台指引,安装探针,并复制初始化代码到您的代码中。




# 示例代码


// 1.安装依赖

// npm i wpk-reporter --save

import wpkReporter from 'wpk-reporter';

const __wpk = new wpkReporter({

bid: '应用标识',

plugins: []

});

// 初始化! 一定要调用

__wpk.installAll();



# 1.3 amd方式接入


wpkReporter.js 是一个umd模块,兼容 普通H5、amd、cmd跟nodejs等多种环境。如果你的页面使用了amd规范的模块加载器,比如 requirejs,那么有下面两种引用方式。


请按照以下步骤和图例说明接入探针。


  1. 在平台创建HTML5应用后,选择 AMD加载器 接入方式,如下图所示。
  2. 按照平台指引,复制初始化代码到您的代码中。



# 示例代码


// 方法一(推荐):将wpkReporter交给requireJS来加载,然后再初始化


// 方法二:先加载wpkReporter,再加载requireJS


// require.js也建议放到底部





# 2、数据上报


通常情况下,若无自定义上报数据需求,那么探针接入已经完成。


如果您有自定义上报数据的需求,探针提供了主动上报数据的API。



# 2.1 上报自定义监控



# API: report(logData)


  • 创建自定义监控项


为了数据能在平台正确展示,首先需要在平台创建一个监控项 「应用设置-监控项管理-添加监控项」。


  • 在你的页面根据业务上报数据

// script引入方式使用window._wpk.report({...}),下同

__wpk.report({

category: 100, //创建监控项时,获得的"监控代码"

msg: 'test', //你要上报的内容

w_succ: 1, // 可选,若监控项需要监控率,则设置此字段可选为0、1

wl_avgv1: 100, // 可选,若监控项需要监控均值,则设置次此字段,必须为数字

c1: 'text' // 可选, 辅助字段,可在日志详情中看到,共有c1~c5 5 个

})





# 3、API


温馨提示

  • 调用api之前,请确保实例本身已被初始化
  • 所有api都返回探针实例本身,因此所有api都可以链式调用


# .report(logData)


主动上报一条自定义日志,日志类容为logData且必填,logData支持的属性如下。


{

category: 100, //日志分类,大于等于100。1~99已被系统预留

msg: 'desc',// 日志描述类容

w_succ: 1, // 可选,用于计算率的标识,可选为1和0

wl_avgv1: 100, // 可选,用于监控如耗时,性能等均值,必须是一个数字

c1: 'xx', //自定义字段1,用于辅助问题排查,将展示在日志详情中,下c2~c5相同,

c2: 'xx',

c3: 'xx',

c4: 'xx',

c5: 'xx',

}




# .reportFlow()


主动上报一条打点日志,上报一次,平台「页面分析」中的PV会增加1。



# .reportError(error)


用于主动上报一条JS Error日志;error为JS Error对象



# .reportApiError(data)


用于主动上报一条API监控日志。


  • data 属性

{

msg: '', // api响应信息

url: '', // api url

 method: '',

queryString: '',

body: '', // 请求body

response: '',

status: '', // http status

spent: 0, // 耗时,,有效值为数字

c1: '', c2: '', c3: '', c4: '', c5: ''

}




  • 适用场景


探针本身已经支持对api进行监控,api请求的成功失败,通过 status  的值判断,若您的api返回值都是200,而通过response body判断中的自定义code判断,建议使用此API自行上报。



# .setConfig(opts)


更新探针实例配置。



# .install()


探针安装,即初始化所有配置和插件后调用此方法,探针才能正常工作。


注意:调用此api安装探针时,只对plugins中已配置的插件生效。



# .installAll()


全家桶式的安装探针,内置所有插件将全部生效。



# .uninstall()


卸载探针实例,销毁所有监听实例,主动上报、自动上报功能不再生效。