Application Real-Time Monitoring Service:Browser Monitoring SDK configuration

Initialization example

This snippet installs the agent with the required pid plus three optional parameters -- enableSPA, sendResource, and release:

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={
  pid: "<your-pid>",
  enableSPA: true,
  sendResource: true,
  release: "1.0.0"
};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
</script>

Runtime updates with setConfig

Call __bl.setConfig(next) to modify configuration after page load.

__bl.setConfig({
    uid: "user-12345",
    tag: "checkout-flow"
});

Identity

Page and URL

SPA support

Data filtering

Sampling

Performance and resource tracking

Tracing and diagnostics

Application metadata

Custom fields

pid

Unique project ID, generated automatically when ARMS creates a site.

uid

User identifier for searching and tracking individual users. Specify a custom value, or let the SDK generate one automatically.

__bl.setConfig({
    uid: "user-12345"
});

setUsername

A callback that returns a username string. Once set, enables end-to-end session tracing and session lookup by username for troubleshooting.

__bl.setConfig({
    setUsername: function () {
        return "username_xxx";
    }
});

Behavior:

• If the username is unavailable at page load, return null -- not a placeholder. The SDK calls setUsername again when sending logs. Returning a placeholder means that value is used and setUsername is not called again.

• setUsername accepts only one assignment per runtime. Restart the application to reassign it.

page

Overrides the automatically detected page name with a custom value.

tag

A custom tag attached to every log entry. Use tags to categorize or filter logs in the ARMS console.

ignoreUrlCase

When set to true, page URL matching is case-insensitive.

urlHelper

Normalizes page URLs by removing dynamic segments so that similar pages aggregate under one entry. Replaces the deprecated ignoreUrlPath parameter.

Why normalize URLs: A URL like example.com/projects/123456 generates a unique page name per project ID. urlHelper strips dynamic segments so all project pages aggregate as example.com/projects/**.

Default value:

[
    // Replace digit sequences (2-20 chars) with **
    {rule: /\/([a-z\-_]+)?\d{2,20}/g, target: '/$1**'},
    // Remove trailing slash
    /\/$/
]

Supported value types:

apiHelper

Normalizes API URLs by removing dynamic segments, the same way urlHelper normalizes page URLs. Replaces the deprecated ignoreApiPath parameter.

Reporting query parameters in API data: To include query parameters (for example, pid in https://arms.console.aliyun.com/apm?pid=fr6fbgbeot), disable automatic reporting with the ignore parameter and call api() manually. For details, see api().

enableSPA

Listens for hashchange events and reports a new page view (PV) on each route change. Enable this for single-page applications (SPAs).

parseHash

Used with enableSPA. When enableSPA is true and a hashchange event fires, parseHash converts the URL hash into a page name for the Page field. For details, see Page data reporting of SPAs.

Default value:

function (hash) {
    var page = hash ? hash.replace(/^#/, '').replace(/\?.*$/, '') : '';
    return page || '[index]';
}

Typically, the default is sufficient. To map hashes to custom page names, override this function:

var PAGE_MAP = {
    '/': 'Homepage',
    '/contact': 'Contact us',
    '/list': 'Data list'
};

window.addEventListener('load', function (e) {
    __bl.setConfig({
        parseHash: function (hash) {
            var key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || 'Unknown page';
        }
    });
});

ignore

Suppresses log reporting for URLs, APIs, JavaScript errors, or resource errors that match specified rules. Contains four sub-properties.

Each sub-property accepts a String, RegExp, Function, or an Array of these types.

__bl.setConfig({
    ignore: {
        ignoreUrls: [
            'http://host1/',                     // Exact string match
            /.+?host2.+/,                        // Regex match
            function(str) {                      // Custom function
                if (str && str.indexOf('host3') >= 0) {
                    return true;   // Suppress
                }
                return false;      // Report
            }
        ]
    }
});

__bl.setConfig({
    ignore: {
        ignoreApis: [
            'api1', 'api2', 'api3',              // String matches
            /^random/,                            // Regex match
            function(str) {                       // Custom function
                if (str && str.indexOf('api3') >= 0) return true;
                return false;
            }
        ]
    }
});

__bl.setConfig({
    ignore: {
        ignoreErrors: [
            'test error',                         // String match
            /^Script error\.?$/,                  // Regex match
            function(str) {                       // Custom function
                if (str && str.indexOf('Unknown error') >= 0) return true;
                return false;
            }
        ]
    }
});

__bl.setConfig({
    ignore: {
        ignoreResErrors: [
            'http://xx/picture.jpg',              // String match
            /jpg$/,                               // Regex match
            function(str) {                       // Custom function
                if (str && str.indexOf('xx.jpg') >= 0) return true;
                return false;
            }
        ]
    }
});

parseResponse

Parses API response data during automatic reporting. Extracts msg and code from the response object.

Default value:

function (res) {
    if (!res || typeof res !== 'object') return {};
    var code = res.code;
    var msg = res.msg || res.message || res.subMsg || res.errorMsg || res.ret || res.errorResponse || '';
    if (typeof msg === 'object') {
        code = code || msg.code;
        msg = msg.msg || msg.message || msg.info || msg.ret || JSON.stringify(msg);
    }
    return {msg: msg, code: code, success: true};
}

Override this function if your API responses use a different structure.

sample

Controls the sampling rate for performance logs and successful API logs. Sampling rate = 1 / sample:

Sampling reduces data volume and collection overhead. To reduce costs, you can also use the ignore parameter to stop reporting data that does not require monitoring. For more information, see ignore.

ARMS compensates for sampling during processing, so aggregate metrics like JS error rate and API failure rate remain accurate. However, individual log details may be lost.

For more information about the affected metrics, see Statistical metrics.

pvSample

Controls the sampling rate for page view (PV) logs. Same formula as sample: sampling rate = 1 / pvSample.

ARMS compensates for sampling during processing, so aggregate metrics such as JS error rate remain accurate.

sendResource

When set to true, reports all static resources loaded on the page at the load event. Use the Session Traces waterfall chart to identify resources causing slow page loads.

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"<your-pid>",sendResource:true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
</script>

useFmp

Enables First Meaningful Paint (FMP) data collection for first-screen rendering analysis.

autoSendPerf

Controls whether performance logs are sent automatically.

disableHook

Disables AJAX request listeners. By default, the SDK intercepts AJAX calls to report API success rates.

enableLinkTrace

Enables front-to-back tracing, correlating browser requests with server-side traces. For details, see Use the front-to-back tracing feature to diagnose API errors.

behavior

Records the sequence of user actions leading up to errors, aiding troubleshooting.

release

Application version string. Set this to compare monitoring data across different releases.

environment

Deployment environment label. Valid values:

disabled

When set to true, disables all log reporting.

c1, c2, c3

Three custom fields attached to every log entry. Carry business-specific data such as VIP level of a user, A/B test group, or feature flags.

__bl.setConfig({
    c1: "premium",
    c2: "experiment-group-B",
    c3: "feature-darkmode"
});