API reference

Operations in this topic

• Data reporting operations: api() | error() | sum() | avg() | reportBehavior() | performance()
• Method operations: setConfig() | setPage() | addBehavior()

api()

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

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

api() syntax:

__bl.api(api, success, time, code, msg)

Example of api()

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

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

[Back to the top]

error()

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

Generally, the SDK listens for global errors on the page and calls this operation 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.

error() syntax:

__bl.error(error, pos)

Example 1 of error(): Listen to and report JS errors on the page.

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

Example 2 of error(): Report a custom error.

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

[Back to the top]

sum()

sum() syntax:

__bl.sum(key, value)

Example of sum():

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

[Back to the top]

avg()

avg() syntax:

__bl.avg(key, value)

Example of avg():

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

[Back to the top]

addBehavior()

You can call the addBehavior() operation 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() operation to add a custom user behavior to the end of the current behavior queue. When a JS error occurs, the operation reports the current behavior queue and clears the queue.

addBehavior() syntax:

__bl.addBehavior(behavior)

Example of addBehavior():

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

[Back to the top]

reportBehavior()

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

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.

reportBehavior() syntax:

__bl.reportBehavior()

reportBehavior() does not have request parameters.

[Back to the top]

performance()

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

Usage of performance():

1. Set the SDK configuration item autoSendPerf 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() (accessed 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() (accessed 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 the top]

setConfig()

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

setConfig() syntax:

__bl.setConfig(next)

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

__bl.setConfig({
    disableHook: true,
    setUserGroup:function () {
        return 'YourUserGroup'
    }
});            

[Back to the top]

setPage()

You can call the setPage() operation to reset the page name of a page. PV is reported again by default. This method is typically used for single-page applications. For more information, see Advanced browser monitoring scenarios.

setPage() syntax:

__bl.setPage(page, sendPv)

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

__bl.setPage(location.hash);            

Example 2 of setPage(): Set the name of the current page to 'homepage' without triggering PV reporting.

__bl.setPage('homepage', false);     

[Back to the top]

FAQ

Q: What do I do if I am not sure whether the SDK has been loaded when I call the __bl.performance() operation?

A: For more information, see Advanced browser monitoring scenarios.

[Back to the top]