Integrate with an Electron application-Cloud Monitor(CMS)-阿里云帮助中心

User Experience Monitoring lets you monitor Electron desktop applications. Integrating the @arms/rum-electron SDK lets you automatically collect data such as performance metrics, crashes, and user behavior during application runtime, and report it to the Cloud Monitor 2.0 console. This helps you improve the stability and user experience of your desktop application. The SDK uses a dual-process architecture: The main process handles crash collection and data reporting, while the renderer process collects data such as PV, performance metrics, Web Vitals, and API requests. All data is sent through an IPC channel and reported from the main process, so you do not need to modify your renderer process code.

Prerequisites

Electron >= 28.0.0
Node.js >= 16
The User Experience Monitoring service is enabled.

Create an application

Log on to the Cloud Monitor 2.0 console.
In the left-side navigation pane, choose User Experience Monitoring > Application List. In the top menu bar, select the target region.
On the Application List page, click Add Application.
In the Create Application panel, click Electron.
In the Electron panel, enter an application name and description, and then click Create.
Note: The application name must be unique. After the application is created, an endpoint address is automatically generated for it.
Record the generated endpoint address, which you will need to initialize the SDK.

Install the SDK

In the root directory of your Electron project, run the following command to install the SDK:

npm install @arms/rum-electron

Note: electron is a peer dependency of the SDK and requires version 28.0.0 or later. If electron is not already installed in your project, you must install it as well.

Initialize the SDK

In your main process entry file (for example, main.ts), call init() before the app.ready event is emitted:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',  // Replace with the endpoint address from the console
  env: 'prod',                  // Environment: 'prod' | 'gray' | 'pre' | 'daily' | 'local'
  version: '1.0.0',             // Application version number
});

Important

You must call init() before Electron's app.ready event is emitted. The SDK needs to register a custom protocol (rum-event://) and a preload script during the early stages of application startup. These actions must be completed before the app.ready event for the SDK to function correctly.

By default, the SDK exhibits the following behaviors:

autoInject defaults to true. The SDK automatically injects the Browser SDK into the renderer process of every BrowserWindow.
No modifications are needed in the renderer process code, and you do not need to add a preload script.
Data is reported from the main process through the IPC channel.

Verify the integration

After initialization, start your Electron application and perform some actions, such as navigating between pages or making network requests. You can use the beforeReport callback to view the reported data in the main process console:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  beforeReport(bundle) {
    console.log('[RUM] Reporting data:', bundle);
    return bundle;
  },
});

After one to two minutes, go to User Experience Monitoring > Applications in the Cloud Monitor 2.0 console and verify that your application is reporting data.

In the console, you can view the following:

Real-time Overview: Core metrics such as PV, UV, JS error count, and API request count.
Session Details: User session traces and page view paths.
Exception Analysis: JS error stack traces, crash analysis, and error distribution.
Performance Analysis: API response time distribution and lists of the slowest APIs.

Advanced usage

Manual injection mode

To prevent the SDK from automatically injecting the Browser SDK into all renderer processes, set autoInject: false and initialize the SDK manually in the specific renderer processes you want to monitor.

Main process initialization:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  autoInject: false,  // Disable auto-injection
});

Renderer process manual initialization:

import armsRum from '@arms/rum-electron/browser';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
});

In manual injection mode, data is collected only from renderer processes where @arms/rum-electron/browser is explicitly initialized. This is useful when you need fine-grained control over the monitoring scope.

Custom partition support

If your BrowserWindow uses a custom partition configuration, you must ensure that the SDK registers a preload script for that partition. The SDK provides two ways to support custom partitions:

Method 1: Configure the partition during initialization

Pass the partition parameter during initialization. The SDK automatically registers the preload script for that partition:

import armsRum from '@arms/rum-electron';
import { BrowserWindow } from 'electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  partition: 'persist:main',  // Must match the partition in BrowserWindow
});

const win = new BrowserWindow({
  webPreferences: {
    partition: 'persist:main',  // Must match the partition in init()
  },
});

Method 2: Register dynamically after initialization

After the SDK is initialized, use registerSession() to dynamically register the preload script for other partitions:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
}).then(() => {
  // Dynamically register for other partitions
  armsRum.registerSession('persist:other');
});

Call registerSession() before creating the corresponding BrowserWindow to ensure the changes apply on the first page load.

Enable SPA route tracking

To automatically collect route change events in a single-page application (SPA), enable SPA route tracking:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  spaMode: true,  // Or 'hash' / 'history'
});

The spaMode parameter supports the following values:

false: Disables SPA route tracking. This is the default. Only full page loads are tracked.
true or 'auto': Automatically detects the router mode, prioritizing hash changes over pathname changes.
'hash': Hash router mode (for example, React HashRouter).
'history': History API router mode (for example, React BrowserRouter).

Enable tracing

Configure the tracing object to enable distributed tracing, which correlates front-end requests with back-end services:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  tracing: {
    enable: true,
    sample: 0.1,              // 10% sampling rate
    propagatorTypes: ['tracecontext', 'b3'],  // Propagation protocols
    allowedUrls: [
      { match: 'https://api.example.com', sample: 0.5 },  // Trace only specified URLs with a 50% sampling rate
    ],
  },
});

The propagatorTypes parameter supports four protocols: tracecontext, b3, b3multi, and jaeger. The allowedUrls parameter specifies which request URLs to trace. If this parameter is omitted, all requests are traced.