How to install the ARMS Browser Monitoring agent by using npm - Application Real-Time Monitoring Service

To use the Browser Monitoring feature of Application Real-Time Monitoring Service (ARMS) to monitor web applications, you must first install the ARMS agent using Content Delivery Network (CDN) or Node Package Manager (npm). This topic describes how to install the ARMS Browser Monitoring agent for a web application using npm.

Installation

Install the @arms/js-sdk package from the npm repository.

npm install @arms/js-sdk --save

Initialization

Initialize the SDK using BrowserLogger.singleton.

const BrowserLogger = require('@arms/js-sdk');
const __bl = BrowserLogger.singleton(
  {
    pid:"your-project-id",
    appType:"web",
    imgUrl:"https://arms-retcode.aliyuncs.com/r.png?",
    // Other config settings.
  }
);

When you install the ARMS Browser Monitoring agent using npm, the web software development kit (SDK) automatically generates a user ID (UID) to collect information such as the number of unique visitors (UVs). The generated UID can be used to identify users but does not contain business attributes. To customize a UID, you can add the following content to the code:

uid: 'xxx', // The UID is used to identify a user. Set the value as needed.

Example:

const BrowserLogger = require('@arms/js-sdk');
const __bl = BrowserLogger.singleton(
  {
    pid:"your-project-id",
    appType:"web",
    uid: 'xxx',
    imgUrl:"https://arms-retcode.aliyuncs.com/r.png?",
    // Other config settings.
  }
);

API reference

@static singleton(): obtain a singleton object

Note

This method applies only when you import the SDK using npm.

Syntax: BrowserLogger.singleton(config,prePipe)

This is a static method that returns a singleton object. The config and prePipe parameters take effect only when the method is called for the first time. Subsequent calls return only the generated instance.

Parameter	Type	Description	Required	Default value
config	Object	The site configuration. For information about other configuration items in config, see SDK Reference.	Yes	None
prePipe	Array	The content to pre-report.	No	None

You can use this method to initialize the SDK at the application entry point or obtain an instance for each call.

Other reporting APIs

Obtain an instance using BrowserLogger.singleton.

const __bl = BrowserLogger.singleton();

For more information about other APIs of __bl, see Frontend API reference.

Config configuration

The config parameters are the same as those for CDN import. For more information, see SDK Reference.

Pre-reporting

To report data from logic that executes before you call BrowserLogger.singleton(), you must use the pre-reporting feature. For more information, see Pre-report data.

const BrowserLogger = require('@arms/js-sdk');
                // The structure of pipe is the same as that for CDN import.
                const pipe = [
                // Report the current HTML page as an API.
                ['api', '/index.html', true, performance.now, 'SUCCESS'], // This is equivalent to __bl.api(api, success, time, code, msg).
                // After the SDK is initialized, automatic SPA parsing is enabled.
                ['setConfig', {enableSPA: true}]
                ];
                const __bl = BrowserLogger.singleton({pid:'Unique site ID'},pipe);

Common SDK configuration items

Browser Monitoring provides a series of SDK configuration items that you can set to meet specific requirements. The following table describes the common configuration items.


pid	String	The unique ID of the project. It is automatically generated by ARMS when it creates a site.	Yes	None
uid	String	The ID of the user. The value is an identifier of the user and can be used to search for the user. You can specify a custom value. If you do not specify this parameter, the SDK is automatically generated and updated every six months.	No	Automatically generated by the SDK
tag	String	The input tag. Each log carries a tag.	No	None
release	String	The version of the application. We recommend that you configure this parameter to view the report information of different versions.	No	`undefined`
environment	String	The environment field. Valid values: prod, gray, pre, daily, and local. The value prod indicates an online environment. The value gray indicates a phased-release environment. The value pre indicates a staging environment. The value daily indicates a daily environment. The value local indicates a local environment.	No	`prod`
sample	Integer	The log sampling configuration. The value is an integer from 1 to 100. The performance logs and success API logs are sampled at the `1/sample` ratio. For more information about the metrics of performance logs and success API logs, see Statistical metrics.	No	`1`
behavior	Boolean	Specifies whether to record the user behavior that reports errors for easy troubleshooting.	No	`true`
enableSPA	Boolean	Listen to hashchange events on the page and report the PV again. This is applicable to single-page application scenarios.	No	`false`
enableLinkTrace	Boolean	For more information about back-to-back Tracing Analysis, see Use the front-to-back tracing feature to diagnose API errors.	No	`false`

Browser Monitoring provides more SDK configuration items to meet advanced requirements. For more information, see SDK Reference.