本文介绍了前端监控 SDK 的一些接口及其使用场景。

SDK 开放了部分数据上报接口,用户可在页面中自行调用来上报更多数据。

api() 接口调用成功率上报

此接口用于上报页面的 API 调用成功率,SDK 默认会监听页面的 AJAX 请求并调用此接口上报。 如果页面的数据请求方式是 JSONP 或者其他自定义方法(例如客户端 SDK 等),可以在数据请求方法中调用api()方法手动上报。

说明 如果要调用此接口,建议在 SDK 配置项中将disabledHook设置为true,具体配置参见 前端监控 SDK 配置项

调用参数说明:__bl.api(api, success, time, code, msg)

参数 类型 描述 是否必须 默认值
api String 接口名 -
success Boolean 是否调用成功 -
time Number 接口耗时 -
code String/Number 返回码 ''
msg String 返回信息 ''

示例

var begin = Date.now(),
    url = '/data/getTodoList.json';

$.ajax({
    url: url,
    data: {id: 123456}
}).done(function (result) {
    var time = Date.now() - begin;
    // 上报接口调用成功
    window.__bl && __bl.api(url, true, time, result.code, result.msg);
    // do something ....
}).fail(function (error) {
    var time = Date.now() - begin;
    // 上报接口调用失败
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message);
    // do something ...
});            

error() 错误信息上报

此接口用于上报页面中的 JS 错误或使用者想关注的异常。

一般情况下,SDK 会监听页面全局的 Error 并调用此接口上报异常信息,但由于浏览器的同源策略往往无法获取错误的具体信息,此时就需要使用者手动上报。

调用参数说明:__bl.error(error, pos)

参数 类型 描述 是否必须 默认值
error Error JS 的 Error 对象 -
pos Object 错误发生的位置,包含以下3个属性 -
pos.filename String 错误发生的文件名 -
pos.lineno Number 错误发生的行数 -
pos.colno Number 错误发生的列数 -

示例1:监听页面的 JS Error 并上报

window.addEventListener('error', function (ex) {
    // 一般事件的参数中会包含pos信息
    window.__bl && __bl.error(ex.error, ex);
});            

示例2:上报一个自定义的错误信息

window.__bl && __bl.error(new Error('发生了一个自定义的错误'), {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});            

sum() 求和统计

此接口用于统计业务中某些事件发生的次数。

调用参数说明:__bl.sum(key, value)

参数 类型 描述 是否必须 默认值
key String 事件名 -
value Number 单次累加上报量,默认 1 1

示例

__bl.sum('event-a');
__bl.sum('event-b', 3);
__bl.sum('group-x::event-c', 2);            

avg() 求平均统计

此接口用于统计业务场景中某些事件发生的平均次数或平均值。

调用参数说明:__bl.avg(key, value)

参数 类型 描述 是否必须 默认值
key String 事件名 -
value Number 统计上报量,默认 0 0

示例

__bl.avg('event-a', 1);
__bl.avg('event-b', 3);

__bl.avg('events::event-c', 10);
__bl.avg('speed::event-d', 142.42);            

addBehavior() 用户行为添加

此接口用于在当前行为队列末尾添加一条自定义用户行为。

SDK 维护一条最大长度为100的用户行为队列,发生 JS error 时上报当前的行为队列,并将队列清空。调用此接口可在当前行为队列末尾添加一条自定义行为。

说明 您需要在 SDK 配置中将behavior配置为 true,才可调用此参数。

调用参数说明: __bl.addBehavior(behavior)

参数 类型 描述 是否必须 默认值
data Object 行为数据。包含:
  • name:行为名称,String类型,必填,最大长度20字符。
  • message:行为内容,String类型,必填,最大长度200字符。
page String 行为发生的页面 location.pathname的值

示例

{
  data: {
    name: 'string',
    message: 'string',
  },
  page: 'string'
}

reportBehavior() 用户行为上报

在调用此接口时,即刻上报当前行为队列,非必须。

若不手动调用此接口,发生 JS Error 会自动触发上报当前行为队列,最大 size 为100条,若超出100条,队列头的行为则被舍弃。

说明 您需要在 SDK 配置中将behavior配置为 true,才可调用此参数。

调用参数说明: __bl.reportBehavior()

无请求参数。

其它接口

非日志上报接口,一般用于修改 SDK 的部分设置项。

setConfig() 修改配置项

用于在 SDK 初始完成后重新修改部分配置项,具体配置参见 前端监控 SDK 配置项

调用参数说明:__bl.setConfig(next)

参数 类型 描述 是否必须 默认值
next Object 需要修改的配置项以及值 -

示例:修改 disableHook 禁用 API 自动上报

__bl.setConfig({
    disableHook: true
});            

setPage() 设置当前页面的 page name

用于重新设置页面的 page name(默认会触发重新上报 PV)。此接口一般用于单页面应用,更多信息请参考前端监控进阶场景

调用参数说明:__bl.setPage(next, sendPv)

参数 类型 描述 是否必须 默认值
page String 新的 page name -
sendPv Boolean 是否上报 PV,默认会上报 true

示例 1 :设置当前页面的 page name 为当前的 URL hash,并重新上报 PV

__bl.setPage(location.hash);            

示例 2 :仅设置当前页面的 page 为'homepage',但不触发 PV 上报

__bl.setPage('homepage', false);     

performance() 手动上报性能日志

如需上报除默认性能指标外的自定义性能指标,则在页面 onLoad 之后调用此方法。

说明 调用此方法的时间必须是在页面 onLoad 之后,否则会因尚未完成默认性能指标采集而导致调用无效。一次 PV 期间只能有效调用一次。

使用方法如下:

  1. 将 SDK 配置项 autoSendPerf 设置为 false,从而关闭自动上报性能指标。
  2. 调用 __bl.performance(Object) 方法。

示例 1:以 CDN 方式接入时

window.onload = () => {
  setTimeout(()=>{
    __bl.performance({cfpt:100, ctti:200, t1:300, …});
  }, 1000); //设置一定的延时,确保默认性能数据采集完成。
};

示例 2:以 npm 包方式接入时

const BrowserLogger = require('alife-logger');
const __bl = BrowserLogger.singleton({pid:'站点唯一ID'});
window.onload = () => {
  setTimeout(()=>{
    __bl.performance({cfpt:100, ctti:200, t1:300, …});
  }, 1000); //设置一定的延时,确保默认性能数据采集完成。
};
说明 自定义性能指标含义:
  • cfpt:自定义首屏时间
  • ctti:自定义首次可交互时间
  • t1 ~ t10:其他自定义性能指标(共计 10 个)

常见问题

问:如果调用 __bl.performance() 方法时不确定 SDK 是否已加载完成怎么办?

答:请参见数据预上报