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

When your web application needs real-time visibility into page performance, JavaScript errors, API success rates, and user behavior, Application Real-Time Monitoring Service (ARMS) Browser Monitoring collects and reports this data through a lightweight SDK. Install the SDK via npm to bundle it with your frontend code at build time, eliminating any runtime impact on page load.

With npm, the SDK is bundled into your application during the build process and has no impact on page load performance. However, errors and resource loads that occur before initialization completes are not captured. To track all events from the earliest point of page load, use the CDN-based setup instead.

Prerequisites

Before you begin, make sure that you have:

An Alibaba Cloud account with ARMS activated
A Browser Monitoring site created in the ARMS console, which provides your pid (project ID) and imgUrl (reporting endpoint)
Node.js and a package manager (npm, yarn, or pnpm) installed

Step 1: Install the SDK

Install the @arms/js-sdk package:

# npm
npm install @arms/js-sdk --save

# yarn
yarn add @arms/js-sdk

# pnpm
pnpm add @arms/js-sdk

Step 2: Initialize the SDK

Import the SDK at your application entry point and call BrowserLogger.singleton() to create a singleton instance. Replace the placeholders with your actual values.

CommonJS syntax:

const BrowserLogger = require('@arms/js-sdk');

const __bl = BrowserLogger.singleton({
  pid: '<your-pid>',              // Project ID from the ARMS console
  appType: 'web',
  imgUrl: '<your-imgUrl>',        // Reporting endpoint from the ARMS console
  // enableSPA: true,             // Uncomment for single-page applications
  // enableLinkTrace: true,       // Uncomment for front-to-back tracing
});

ES module syntax:

import BrowserLogger from '@arms/js-sdk';

const __bl = BrowserLogger.singleton({
  pid: '<your-pid>',              // Project ID from the ARMS console
  appType: 'web',
  imgUrl: '<your-imgUrl>',        // Reporting endpoint from the ARMS console
});

Replace the following placeholders with your actual values:

Placeholder	Description	Where to find it
`<your-pid>`	Unique project ID	Automatically generated by ARMS when you create a site
`<your-imgUrl>`	Data reporting endpoint URL	Provided when you create a Browser Monitoring site. Example: `https://arms-retcode.aliyuncs.com/r.png?`

Note

Note: BrowserLogger.singleton() is a static method that returns a singleton object. The config and prePipe parameters take effect only on the first call. Subsequent calls return the existing instance.

Set a custom user ID

By default, the SDK generates a user ID (UID) to track unique visitors (UVs). This auto-generated UID can be used to search for the user, updates every six months, and does not contain business attributes.

To use your own identifier, add the uid parameter:

const __bl = BrowserLogger.singleton({
  pid: '<your-pid>',
  appType: 'web',
  uid: '<your-custom-uid>',       // Custom user identifier
  imgUrl: '<your-imgUrl>',
});

Step 3: Verify your setup

After you deploy your application with the SDK initialized:

Open your application in a browser and interact with the page.
Log in to the ARMS console and go to Browser Monitoring.
Select your application and check whether page view (PV) data and performance metrics appear on the overview page.

If no data appears, check the browser console for errors and verify that your pid and imgUrl values are correct.

Configuration reference

The config parameters are the same as those for CDN import. Common SDK parameters are listed below. For the full list, see SDK reference.

Parameter	Type	Required	Default	Description
`pid`	String	Yes	None	Unique project ID. Automatically generated by ARMS when you create a site.
`uid`	String	No	Auto-generated	User identifier for tracking unique visitors. You can use this value to search for the user. If omitted, the SDK generates one and rotates it every six months.
`tag`	String	No	None	Custom tag attached to every log entry.
`release`	String	No	`undefined`	Application version. Set this to compare metrics across releases.
`environment`	String	No	`prod`	Deployment environment. Valid values: `prod` (production), `gray` (phased-release), `pre` (staging), `daily` (daily build), `local` (local development).
`sample`	Integer	No	`1`	Sampling ratio for performance logs and successful API logs. Integer from 1 to 100. Logs are sampled at a `1/sample` ratio. For details, see Statistical metrics.
`behavior`	Boolean	No	`true`	Record user behavior leading up to errors for easier troubleshooting.
`enableSPA`	Boolean	No	`false`	Listen for `hashchange` events and re-report PV data. Enable this for single-page applications (SPAs).
`enableLinkTrace`	Boolean	No	`false`	Enable front-to-back tracing to correlate frontend requests with backend traces. For details, see Use front-to-back tracing to diagnose API errors.

Report pre-initialization data

If some logic runs before BrowserLogger.singleton() is called, pass a prePipe array as the second argument to queue that data for reporting. The pipe structure follows the same format as the CDN-based setup.

const BrowserLogger = require('@arms/js-sdk');

// Queue data to report before the SDK initializes
const pipe = [
  // Report the current page as an API call
  // Equivalent to: __bl.api(api, success, time, code, msg)
  ['api', '/index.html', true, performance.now, 'SUCCESS'],

  // Enable SPA mode after initialization
  ['setConfig', { enableSPA: true }],
];

const __bl = BrowserLogger.singleton({ pid: '<your-pid>' }, pipe);

For more details, see Pre-report data.

API reference

BrowserLogger.singleton(config, prePipe)

Static method that returns a singleton BrowserLogger instance. Available only when you import the SDK via npm.

Parameter	Type	Required	Default	Description
`config`	Object	Yes	None	Site configuration object. See Configuration reference and SDK reference.
`prePipe`	Array	No	None	Array of pre-queued data to report on initialization.

Call this method at your application entry point to initialize the SDK, or from any module to retrieve the existing instance:

// Retrieve the existing singleton instance from any module
const __bl = BrowserLogger.singleton();

Reporting methods

Use the __bl instance to report custom data. For the full API list, see Frontend API reference.