API reference

Methods in this topic

• Methods for data reporting: api(), error(), sum(), avg(), reportBehavior(), and performance()
• Methods for SDK configuration modification: setConfig(), setPage(), setCommonInfo(), and addBehavior()

api()

You can call the api() method to report the success rate of API calls on a page.

By default, the SDK listens to Asynchronous JavaScript and XML (AJAX) requests on the page and calls this method to report data. If data on the page is requested by using JSON with Padding (JSONP) or other custom tools such as the client SDK, you can call the api() method in the data request for manual reporting.

Syntax of 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})

Example of api():

var begin = Date.now(),
    url = '/data/getTodoList.json',
    traceId = window.__bl && __bl.getTraceId('EagleEye-TraceID'),
    sid = window.__bl && __bl.getSessionId('EagleEye-SessionID');
// Specify EagleEye-TraceID and EagleEye-SessionID in the request header.
fetch(url, {
    headers: {
        'EagleEye-TraceID': traceId,
        'EagleEye-SessionID': sid
    }
}).then(function (result) {
    var time = Date.now() - begin;
    // Report that the call is successful.
    window.__bl && __bl.api(url, true, time, result.code, result.msg, begin, traceId, sid);
    // do something ....
}).catch(function (error) {
    var time = Date.now() - begin;
    // Report that the call fails.
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message, begin, traceId, sid);
    // do something ...
});    

[Back to Top]

error()

You can call the error() method to report JavaScript (JS) errors or exceptions that you want to capture on a page.

Generally, the SDK listens to global errors on the page and calls this method to report exceptions. However, error details are usually out of reach due to the same-origin policy of the browser. In this case, you must manually report such errors.

__bl.error(error, pos)

window.addEventListener('error', function (ex) {
    // Event parameters usually contain location information. 
    window.__bl && __bl.error(ex.error, ex);
});            

window.__bl && __bl.error(new Error('A custom error occurs.'), {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});            

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

[Back to Top]

sum()

Syntax of sum():

__bl.sum(key, value)

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

[Back to Top]

avg()

__bl.avg(key, value)

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

[Back to Top]

reportBehavior()

You can call the reportBehavior() method to immediately report the current behavior queue.

If you do not manually call this method, when a JS error occurs, the current behavior queue is automatically reported. The maximum size of a queue is 100. If the queue contains more than 100 behavior records, behavior records are discarded from the header of the queue.

Syntax of reportBehavior():

__bl.reportBehavior()

The reportBehavior() method does not have request parameters.

[Back to Top]

performance()

After the onLoad method is called, the performance() method is called to report custom performance metrics other than the default performance metrics.

How to call the performance() method:

1. Set the autoSendPerf parameter to false to disable automatic reporting of performance metrics and wait for manual reporting.
2. Call the __bl.performance(Object) method to manually report custom performance metrics. In this process, the default performance metrics are automatically reported.

Example 1 of performance() (by using CDN):

window.onload = () => {
  setTimeout(()=>{
__bl.performance({cfpt:100, ctti:200, t1:300, …});
}, 1000); // Set a delay to ensure that the default performance data is collected. 
};

Example 2 of performance() (by using npm packages):

const BrowserLogger = require('alife-logger');
const __bl = BrowserLogger.singleton({pid:'Unique site ID'});
window.onload = () => {
  setTimeout(()=>{
__bl.performance({cfpt:100, ctti:200, t1:300, …});
}, 1000); // Set a delay to ensure that the default performance data is collected. 
};

[Back to Top]

setConfig()

You can call the setConfig() method to modify specific configuration items after the SDK initialization. For more information, see SDK reference.

Syntax of setConfig():

__bl.setConfig(next)

Example of setConfig(): change the value of the disableHook parameter to disable automatic API reporting.

__bl.setConfig({
    disableHook: true
});            

[Back to Top]

setPage()

You can call the setPage() method to reset the name of a page. By default, PV data is reported again. This method is typically used for single-page applications (SPAs). For more information, see Page data reporting of SPAs.

Syntax of setPage():

__bl.setPage(page, sendPv)

Set the name of the current page to the current URL hash, and report PV data again.
__bl.setPage(location.hash);

Set the name of the current page to homepage without triggering PV data reporting.
__bl.setPage('homepage', false);          

[Back to Top]

setCommonInfo()

You can call the setCommonInfo() method to set common fields.

Syntax of setCommonInfo():

__bl.setCommonInfo(obj)

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

[Back to Top]

addBehavior()

You can call the addBehavior() method to add a custom user behavior to the end of the current behavior queue.

The SDK maintains a user behavior queue with a maximum of 100 records. You can call the addBehavior() method to add a custom user behavior to the end of the current behavior queue. When a JS error occurs, the addBehavior() method reports the current behavior queue and clears the queue.

Syntax of addBehavior():

__bl.addBehavior(behavior)

Example of addBehavior():

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

[Back to Top]

Create multiple instances

Use npm packages to create multiple instances. The official npm package alife-logger has been published.

Web pages

• Example:

  const BrowerLogger = require('alife-logger');
  const bl2 = BrowerLogger.createExtraInstance(props); // Create instances by using the createExtraInstance method.
  bl2.custom({
    key: 'biz',
    msg: 'msg info'
  });

  Note The props parameter is of the Object type. The parameters contained in the props parameter are basically the same as those in the SDK configurations.
• The new instances report only custom information:

  var props = {
    pid: 'xxxx', // The ID of the site whose data the new instances need to report.
    region: 'cn',
    page: '',
    uid: ''
  }

Weex pages

• Example:

  const WeexLogger = require('alife-logger/weex');
  const wl2 = WeexLogger.createExtraInstance(props); // Create instances by using the createExtraInstance method.
  wl2.custom({
    key: 'biz',
    msg: 'msg info'
  });

  Note The props parameter is of the Object type. The parameters contained in the props parameter are basically the same as those in the SDK configurations.
• The new instances report only custom information:

  var props = {
    pid: 'xxxx', // The ID of the site whose data the new instances need to report.
    region: 'cn',
    sendRequest: function(data, imgUrl) {
      // Send the GET log scheme.
    },
    postRequest: function(data, imgUrl) {
      // Send the POST log scheme.
    }
  }

Mini-programs

import MiniProgramLogger from 'alife-logger/miniprogram'; // Specify the path based on the type of the mini-program, such as the DingTalk or Alipay mini-program.
const MiniInstance = MiniProgramLogger.createExtraInstance({
  pid: 'xxxinstance',
  uid: 'userxxx', // The ID of the user, which is used to collect the UV data.
  region: 'cn', // Specify the region where the application to which logs are to be reported is deployed. A value of cn indicates China, and a value of sg indicates Singapore. If you do not specify the region ID, the region is China.
  // Specify the remote procedure call (RPC) method based on your business to perform browser monitoring of mini-programs.
  sendRequest: (url, resData) => {
    // The sending method.
  }
});