文档

前端接口说明

更新时间:

前端监控SDK开放了部分接口,包括用于上报数据的数据上报类接口和用于修改SDK配置项的方法类接口。

本页索引

api()

调用api()接口来上报页面的API调用成功率。

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

说明

如果要调用此接口,建议在SDK配置项中将disableHook设置为true。更多信息,请参见disableHook

api()语法:

__bl.api(api, success, time, code, msg, begin, traceId, sid)

或者

__bl.api({api: xxx, success: xxx, time: xxx, code: xx, msg: xx, begin: xx, traceId: xx, sid: xx})
表 1. api()调用参数

参数

类型

描述

是否必选

默认值

api

String

接口名

success

Boolean

是否调用成功

time

Number

接口耗时

code

String/Number

返回码

msg

String

返回信息

begin

Number

API请求开始时间戳

traceId

String

EagleEye-TraceID的值

sid

String

EagleEye-SessionID的值

api()使用示例:

var begin = Date.now(),
    url = '/data/getTodoList.json',
    traceId = window.__bl && __bl.getTraceId('EagleEye-TraceID'),
    sid = window.__bl && __bl.getSessionId('EagleEye-SessionID');
// 备注:请求的header部分请加入EagleEye-TraceID、EagleEye-SessionID
fetch(url, {
    headers: {
        'EagleEye-TraceID': traceId,
        'EagleEye-SessionID': sid
    }
}).then(function (result) {
    var time = Date.now() - begin;
    // 上报接口调用成功
    window.__bl && __bl.api(url, true, time, result.code, result.msg, begin, traceId, sid);
    // do something ....
}).catch(function (error) {
    var time = Date.now() - begin;
    // 上报接口调用失败
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message, begin, traceId, sid);
    // do something ...
});    

[回到顶部]

error()

调用error()接口来上报页面中的JS错误或使用者想关注的异常。您可以在前端监控的JS错误诊断页面查询相关信息。

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

error()语法:

__bl.error(error, pos)
表 2. error()调用参数

参数

类型

描述

是否必选

默认值

error

Error

JS的Error对象

pos

Object

错误发生的位置,包含pos.filenamepos.linenopos.colno属性。

pos.filename

String

错误发生的文件名

pos.lineno

Number

错误发生的行数

pos.colno

Number

错误发生的列数

error()使用示例1:监听页面的JS Error并上报。

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

error()使用示例2:上报一个自定义的错误信息。

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

error()使用示例3:上报一个自定义类型的错误信息。

__bl.error({name:'CustomErrorLog',message:'this is an error'}, {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});           

[回到顶部]

sum()

调用sum()方法,可以自定义上报的日志,它通常被用于统计业务中特定事件发生的次数。通过sum()方法上报的数据,您可以在自定义统计页面查看:

说明

统计数据存在一些延迟,请等待几分钟后查看。

  • 自定义事件发生的趋势图。

  • 发生该事件的PV或UV统计。

  • 维度分布信息。

sum()语法:

__bl.sum(key, value)
表 4. sum()调用参数

参数

类型

描述

是否必选

默认值

key

String

事件名

value

Number

单次累加上报量

1

sum()使用示例:

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

[回到顶部]

avg()

调用avg()可以自定义上报的日志,它通常被用于计算业务中特定事件发生的平均次数或平均值。通过avg()方法上报的数据,您可以在自定义统计页面查看:

  • 自定义事件发生的趋势图。

  • 发生该事件的PV或UV统计。

  • 维度分布信息。

avg()语法:

__bl.avg(key, value)
表 5. avg()调用参数

参数

类型

描述

是否必选

默认值

key

String

事件名

value

Number

统计上报量

0

avg()使用示例:

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

[回到顶部]

reportBehavior()

调用reportBehavior()接口即刻上报当前行为队列。

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

说明

您需要在SDK配置中将behavior配置为true,才可调用此方法。

reportBehavior()语法:

__bl.reportBehavior()

reportBehavior()调用参数:无请求参数。

[回到顶部]

performance()

重要

仅支持在Web端使用。

在页面onLoad之后调用performance()接口来上报除默认性能指标外的自定义性能指标。

说明

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

performance()使用方法:

  1. 将SDK配置项autoSendPerf设置为false,从而关闭自动上报性能指标,并等待手动触发上报。

  2. 调用__bl.performance(Object)方法来手动上报自定义指标,此过程中也会自动上报默认性能指标。

performance()使用示例1(以CDN方式接入时):

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

performance()使用示例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个)。

[回到顶部]

setConfig()

在SDK初始完成后调用setConfig()接口来重新修改部分配置项,关于SDK配置项的详细信息,请参见SDK配置项

setConfig()语法:

__bl.setConfig(next)
表 8. setConfig()调用参数

参数

类型

描述

是否必选

默认值

next

Object

需要修改的配置项以及值。

[回到顶部]

setPage()

调用setPage()接口来重新设置页面的page name(默认会触发重新上报PV)。此接口一般用于单页面应用,更多信息,请参见SPA页面上报

说明

重新上报PV不会覆盖之前的数据,而是增加一条PV数据。

setPage()语法:

__bl.setPage(page, sendPv)
表 9. setPage()调用参数

参数

类型

描述

是否必选

默认值

page

String

新的page name。

sendPv

Boolean

是否上报PV,默认会上报。

true

setPage()使用示例:

// 设置当前页面的page name为当前的URL hash,并重新上报PV
__bl.setPage(location.hash);

// 仅设置当前页面的page为'homepage',但不触发PV上报
__bl.setPage('homepage', false);          

[回到顶部]

setCommonInfo()

调用setCommonInfo()用于设置公共字段。

setCommonInfo()语法:

__bl.setCommonInfo(obj)

setCommonInfo()其中入参是object,示例如下:

__bl.setCommonInfo({
  name: 'xxx',
  common: 'xxx'
});          
说明

该方法建议object信息不要太大,否则容易导致GET请求过长,从而导致请求失败的问题。

[回到顶部]

addBehavior()

调用addBehavior()接口在当前行为队列末尾添加一条自定义用户行为。

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

您可以在JS错误诊断页面查看用户行为回溯,具体操作,请参见使用用户行为回溯诊断JS错误

说明

您需要在SDK配置中将behavior配置为true,才可调用此方法。

addBehavior()语法:

__bl.addBehavior(behavior)
表 10. addBehavior()调用参数

参数

类型

描述

是否必选

默认值

data

Object

行为数据。包含:

  • name:行为名称,String类型,必填,最大长度20字符。

  • message:行为内容,String类型,必填,最大长度200字符。

page

String

行为发生的页面。

location.pathname的值

addBehavior()使用示例:

_bl.addBehavior({
  data:{name:'string',message:'sting'},
  page:'string'
})

[回到顶部]

创建多实例方法

创建多实例请使用NPM包方式,现在正式版NPM包已发布,NPM包:alife-logger 。

Web页面

  • 使用方法:

    const BrowerLogger = require('alife-logger');
    const bl2 = BrowerLogger.createExtraInstance(props); // 通过createExtraInstance 创建实例
    bl2.custom({
      key: 'biz',
      msg: 'msg info'
    });
    说明

    其中props为Object,具体的参数与SDK的config基本保持一致。

  • 如果新实例只上报自定义信息:

    var props = {
      pid: 'xxxx', //新实例需要上报的站点
      region: 'cn',
      page: '',
      uid: ''
    }

Weex页面

  • 使用方法:

    const WeexLogger = require('alife-logger/weex');
    const wl2 = WeexLogger.createExtraInstance(props); // 通过createExtraInstance 创建实例
    wl2.custom({
      key: 'biz',
      msg: 'msg info'
    });
    说明

    其中props为Object,具体的参数与SDK的config基本保持一致。

  • 如果新实例只上报自定义信息:

    var props = {
      pid: 'xxxx', //新实例需要上报的站点
      region: 'cn',
      sendRequest: function(data, imgUrl) {
        // 发送Get日志方案
      },
      postRequest: function(data, imgUrl) {
        // 发送POST日志方案
      }
    }

小程序页面

使用方法:

import MiniProgramLogger from 'alife-logger/miniprogram'; // 具体路径是根据钉钉小程序、支付宝小程序及其他类小程序来选择对应的路径。
const MiniInstance = MiniProgramLogger.createExtraInstance({
  pid: 'xxxinstance',
  uid: 'userxxx', // 用来设置用户uid,统计UV信息。
  region: 'cn', // region为cn、sg分别表示是日志上报到中国服务器、还是新加坡服务器,如不配置默认是中国服务器。
  // 基础小程序监控需要手动传入rpc(方法实现按照实际业务来写)。
  sendRequest: (url, resData) => {
    // 发送方法。
  }
});