The Browser Monitoring SDK provides methods to report data and modify SDK configurations.
Methods in this topic
- Methods for data reporting:
api()
,error()
,sum()
,avg()
,reportBehavior()
, andperformance()
- Methods for SDK configuration modification:
setConfig()
,setPage()
,setCommonInfo()
, andaddBehavior()
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)
or __bl.api({api: xxx, success: xxx, time: xxx, code: xx, msg: xx, begin: xx, traceId: xx, sid: xx})
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
api | String | The name of the method. | Yes | None |
success | Boolean | Specifies whether the call is successful. | Yes | None |
time | Number | The amount of time consumed by the call. | Yes | None |
code | String/Number | The return code. | No | '' |
msg | String | The response information. | No | '' |
begin | Number | The timestamp when the API call started. | No | '' |
traceId | String | The value of EagleEye-TraceID. | No | '' |
sid | String | The value of EagleEye-SessionID. | No | '' |
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 ...
});
error()
You can call the error()
method to report JavaScript (JS) errors or exceptions that you want to capture on
a page. You can view the details of JS errors on the JS Error Diagnosis page of Browser Monitoring.
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.
error()
:__bl.error(error, pos)
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
error | Error | The JS error object. | Yes | None |
pos | Object | The location where the error occurs. The location contains the following attributes: pos.filename, pos.lineno, and pos.colno. | No | None |
pos.filename | String | The name of the file where the error occurs. | No | None |
pos.lineno | Number | The number of the line where the error occurs. | No | None |
pos.colno | Number | The number of the column where the error occurs. | No | None |
error()
: listen to and report JS errors on a page. window.addEventListener('error', function (ex) {
// Event parameters usually contain location information.
window.__bl && __bl.error(ex.error, ex);
});
error()
: report a custom error. window.__bl && __bl.error(new Error('A custom error occurs.'), {
filename: 'app.js',
lineno: 10,
colno: 15
});
error()
: report errors of a specified custom type. __bl.error({name:'CustomErrorLog',message:'this is an error'}, {
filename: 'app.js',
lineno: 10,
colno: 15
});
sum()
sum()
method to customize the logs to be reported. The logs are used to count how many
times a specific event occurs in a business scenario. You can view the following data
reported by calling the sum()
method on the Custom Statistics page:
- Trend chart of custom events
- Page views (PVs) and unique visitors (UVs) of an event
- Dimension distribution information
Syntax of sum()
:
__bl.sum(key, value)
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
key | String | The name of the event. | Yes | None |
value | Number | The number of reported items at a time. | No | 1 |
sum()
:__bl.sum('event-a');
__bl.sum('event-b', 3);
avg()
avg()
method to customize the logs to be reported. The logs are used to count how many
times a specific event occurs on average in a business scenario. You can view the
following data reported by the avg()
method on the Custom Statistics page:
- Trend chart of custom events
- PVs and UVs of an event
- Dimension distribution information
avg()
:__bl.avg(key, value)
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
key | String | The name of the event. | Yes | None |
value | Number | The number of reported items. | No | 0 |
avg()
:__bl.avg('event-a', 1);
__bl.avg('event-b', 3);
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.
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:
- Set the autoSendPerf parameter to false to disable automatic reporting of performance metrics and wait for manual reporting.
- 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.
};
- cfpt: the custom first paint time
- ctti: the custom first time to interact
- t1 to t10: 10 custom performance metrics
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)
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
next | Object | The parameter that you want to modify and the new parameter value. | Yes | None |
Example of setConfig()
: change the value of the disableHook parameter to disable automatic API reporting.
__bl.setConfig({
disableHook: true
});
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)
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
page | String | The new page name. | Yes | None |
sendPv | Boolean | Specifies whether to report PV data. By default, PV data is reported. | No | true |
setPage()
:// 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);
setCommonInfo()
You can call the setCommonInfo()
method to set common fields.
Syntax of setCommonInfo()
:
__bl.setCommonInfo(obj)
setCommonInfo()
method. Example of setCommonInfo():__bl.setCommonInfo({
name: 'xxx',
common: 'xxx'
});
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.
You can view user behaviors on the JS Error Diagnosis page. For more information, see Diagnose JS errors by backtracking user behaviors.
Syntax of addBehavior()
:
__bl.addBehavior(behavior)
Parameter | Type | Description | Required | Default value |
---|---|---|---|---|
data | Object | The behavior data. This parameter has the following two required fields:
|
Yes | None |
page | String | The page where the behavior happens. | No | Value of the location.pathname parameter |
Example of addBehavior()
:
_bl.addBehavior({
data:{name:'string',message:'sting'},
page:'string'
})
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 whether the application to which logs are to be reported is deployed in China or Singapore. The value cn indicates China and the value sg indicates Singapore. If you do not specify this parameter, the value is set to cn.
// Specify the remote procedure call (RPC) method based on your business to perform browser monitoring of mini-programs.
sendRequest: (url, resData) => {
// The sending method.
}
});