edit-icon download-icon

API user guide

Last Updated: Apr 11, 2018

This topic describes some interfaces of browser monitoring SDK and their usage.

Log reporting API

The SDK opens some data reporting APIs, which can be called on the page to report more data.

api() for reporting the API call success rate

This API reports the API call success rate on the page. The SDK listens for AJAX requests on the page and calls this API for reporting by default. If data on the page is requested using JSONP or other custom methods (such as the client SDK), you can call api() in the data request method for manual reporting.

NOTE: To call this API, you are advised to set disabledHook to true in SDK configuration items. For detailed configuration, see SDK configuration items.

Call parameter description: __bl.api(api, success, time, code, msg)

Parameter Type Description Required Default value
api String The API name Yes -
success Boolean If the call is successful Yes -
time Number The time consumed on the API Yes -
code String/Number The return code No ''
msg String The return information No ''

Example

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

$.ajax({
    url: url,
    data: {id: 123456}
}).done(function (result) {
    var time = Date.now() - begin;
    // Report that the API call is successful.
    window.__bl && __bl.api(url, true, time, result.code, result.msg);
    // do something ....
}).fail(function (error) {
    var time = Date.now() - begin;
    // Report that the API call fails.
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message);
    // do something ...
});

error() for reporting the error information

This API reports JS errors or exceptions you want to capture on the page.

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

Call parameter description: __bl.error(error, pos)

Parameter Type Description Required Default value
error Error The JS error object Yes -
pos Object The location of the error including the following three attributes No -
pos.filename String The file in which the error occurs No -
pos.lineno Number The row where the error occurs No -
pos.colno Number The column where the error occurs No -

Example 1: Listen for JS errors on the page and report

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

Example 2: Report a custom error

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

sum() for sum total

This API counts how many times a specific business event occurs.

Call parameter description: __bl.sum(key, value)

Parameter Type Description Required Default value
key String Event name Yes -
value Number Increment of each time, which is 1 by default. No 1

Example

__bl.sum('event-a');

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

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

avg() for averages

This API counts how many times a specific event occurs on average in a business scenario.

Call parameter description: __bl.avg(key, value)

Parameter Type Description Required Default value
key String The event name Yes -
value Number The reported number, which is 0 by default. No 0

Example

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

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

Other APIs

Non-log reporting APIs are usually used for modifying some configuration items of the SDK.

setConfig() for modifying configuration items

This API re-modifies some of the configuration items after SDK initialization. For detailed configuration, see SDK configuration items.

Call parameter description: __bl.setConfig(next)

Parameter Type Description Required Default value
next Object The configuration item to be modified and its value No -

Example: Modify disableHook to disable automatic API reporting

__bl.setConfig({
    disableHook: true
});

setPage() for setting the name of the current page

This API resets the page name of a page. PV will be reported again by default. This API is usually used in single page application (SPA) scenarios. For more information, see Introduction to advanced scenarios.

Call parameter description: __bl.setPage(next, sendPv)

Parameter Type Description Required Default value
page String The new page name Yes -
sendPv Boolean If to report PV. PV is reported by default. No true

Example 1: Set the name of the current page to the current URL hash, and report PV again.

__bl.setPage(location.hash);

Example 2: Set the new name of the current page to “homepage” without triggering PV reporting

__bl.setPage('homepage', false);
Thank you! We've received your feedback.