Application Real-Time Monitoring Service:RUM SDK configuration reference for web and HTML5

CDN initialization

When loading the SDK through Alibaba Cloud Content Delivery Network (CDN), access it from the RumSDK.default global namespace:

const ArmsRum = window.RumSDK.default;

// Initialize the SDK after it has loaded.
// Skip this step if you defined window.__rum before the SDK script tag.
ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

// Update configuration at runtime
ArmsRum.setConfig('env', 'pre');

npm initialization

import ArmsRum from '@arms/rum-browser';

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  user: {
    name: 'your user.name',
    tags: 'your user.tags',
  },
});

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  reportConfig: {
    flushTime: 0,       // Report immediately
    maxEventCount: 50,  // Up to 50 events per batch
  },
});

Storage details

The storage parameter determines where the SDK persists the following data:

• _arms_uid -- the unique user ID (user.id)

• _arms_session -- session metadata in the format ${sessionId}-${sampled}-${startTime}-${lastTime}:

  • sessionId -- unique session identifier

  • sampled -- whether this session was selected by sampling

  • startTime -- session start timestamp

  • lastTime -- last activity timestamp

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  sessionConfig: {
    sampleRate: 0.5,          // Sample 50% of sessions
    maxDuration: 86400000,    // 24-hour maximum
    overtime: 3600000,        // 1-hour inactivity timeout
    storage: 'cookie',        // Use cookie instead of localStorage
  },
});

Example

Disable user interaction tracking:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  collectors: {
    action: false,
  },
});

Input arguments

Return type (IApiBaseAttr)

Returned fields override the SDK defaults. Omitted fields keep their default values.

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  evaluateApi: async (options, response, error) => {
    let respText = '';
    if (response && response.text) {
      respText = await response.text();
    }

    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      snapshots: JSON.stringify({
        params: 'page=1&size=10',
        response: respText.substring(0, 2000),
        reqHeaders: '',
        resHeaders: '',
      }),
      properties: {
        prop_msg: 'custom msg',
        prop_num: 1,
      },
    };
  },
});

MatchOption type

type MatchOption = string | RegExp | ((value: string) => boolean);

• String -- matches any URL or message that starts with the specified value. For example, 'https://api.aliyun.com' matches 'https://api.aliyun.com/v1/resource'.

• RegExp -- matches URLs or messages against a regular expression.

• Function -- receives the URL or message as input. Return true to exclude the event.

When you pass an array of MatchOption values, conditions are evaluated in order. An event is excluded if any condition matches.

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  filters: {
    exception: [
      'Test error',                           // Messages starting with 'Test error'
      /^Script error\.?$/,                    // Messages matching this regex
      (msg) => msg.includes('example-error'), // Custom match function
    ],
    resource: [
      'https://example.com/',   // URLs starting with 'https://example.com/'
      /localhost/i,             // URLs containing 'localhost'
      (url) => url.includes('example-resource'),
    ],
  },
});

DetectionRule

Trigger events

Detection methods

CustomTesterResult type:

type CustomTesterResult = {
  hasContent: boolean;               // true = content exists; false = white screen detected
  message?: string;                  // Error message
  snapshot?: Record<string, any>;    // Diagnostic data
}

ConfigOptions

Options specific to the SCREENSHOT and SAMPLE detection methods.

SCREENSHOT options:

SAMPLE options:

Shared option:

Both SCREENSHOT and SAMPLE support the debug option (Boolean, default: false). When enabled, detection details are printed to the browser developer tools console.

Examples

Screenshot-based detection:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SCREENSHOT',
      configOptions: {
        colorRange: ['rgb(255, 255, 255)', 'rgb(0, 0, 0)'],
        threshold: 0.9,
        pixels: 10,
        horizontalOffset: 210,
        verticalOffset: 50,
      },
    }],
  },
});

Sampling-based detection:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SAMPLE',
      configOptions: {
        sampleMethod: 2,
        checkPoints: 10,
        threshold: 0.9,
        whiteBoxElements: ['.el-skeleton'],
      },
    }],
  },
});

Custom detection function:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: async (element) => {
        return {
          hasContent: false,
          message: 'Custom error message',
          snapshot: {
            checkPoints: 100,
            rate: 0.99,
            checkdata: '......',
          },
        };
      },
    }],
  },
});

Merge behavior

• Global properties (set in init()) and event-level properties (set through evaluateApi, sendCustom, sendException, or sendResource) are merged at storage time.

• Event-level properties take precedence. If the same key exists in both, the event-level value wins.

• After merging, a maximum of 20 key-value pairs are kept. Excess pairs are sorted by key and removed.

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // Keys longer than 50 characters are truncated
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    // String values longer than 2,000 characters are truncated
    more_than_2000_value_limit: new Array(2003).join('1'),
    // Invalid types -- these pairs are removed
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Step 1: Configure in the ARMS console

1. Go to Application List and open your application.

2. Go to Application Settings > SDK config.

3. Set the desired configuration values.

4. Click Confirm Update Dynamic Configuration to push the settings to the remote Object Storage Service (OSS) server.

Step 2: Enable in the SDK

Add the remoteConfig field to your initialization code with the region where your application is hosted.

CDN:

window.__rum = {
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // Example: "ap-southeast-1" for Singapore
  }
};

<script async src="https://xxid-sdk.rum.aliyuncs.com/v2/browser-sdk.js"></script>

npm:

import ArmsRum from '@arms/rum-browser';

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // Example: "ap-southeast-1" for Singapore
  }
});

Caching behavior

After retrieving the remote configuration, the SDK caches the settings locally. On subsequent initializations, the SDK prioritizes the cached configuration.

Dynamic configuration requires SDK version 0.0.37 or later when importing through CDN with a pinned version.

Example

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  geo: {
    country: 'your custom country info',
    city: 'your custom city info',
  },
});

getConfig

Retrieve the current SDK configuration:

const config = ArmsRum.getConfig();

setConfig

Update SDK configuration at runtime. Pass a single key-value pair or a full configuration object:

// Set a single value
ArmsRum.setConfig('env', 'pre');

// Set multiple values
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

Report a custom event. The type and name fields are required.

ArmsRum.sendCustom({
  type: 'CustomEventType1',
  name: 'customEventName2',
  group: 'customEventGroup3',
  value: 111.11,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendException

Report a custom exception. The name and message fields are required.

ArmsRum.sendException({
  name: 'customErrorName',
  message: 'custom error message',
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendResource

Report a custom resource event. The name, type, and duration fields are required.

ArmsRum.sendResource({
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});