API user guide

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)

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)

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)

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)

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)

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)

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);