接入 Electron 应用-云监控(CMS)-阿里云帮助中心

用户体验监控支持监控Electron桌面应用，通过集成@arms/rum-electron SDK，自动采集应用运行过程中的性能指标、异常崩溃、用户行为等数据，并上报至ARMS控制台，帮助您提升桌面应用的稳定性和用户体验。SDK采用双进程架构：主进程负责异常崩溃采集与数据上报，渲染进程负责PV、性能、Web Vitals、API请求等数据采集，数据通过IPC通道统一在主进程上报，无需修改渲染进程代码。

前提条件

Electron >= 28.0.0
Node.js >= 16
已开通ARMS用户体验监控服务

创建应用

登录ARMS控制台。
在左侧导航栏选择用户体验监控 > 应用列表，并在顶部菜单栏选择目标地域。
在应用列表页面单击添加应用。
在创建应用面板单击Electron。
在Electron面板上输入应用名称和描述，然后单击创建。
说明：应用名称唯一，不能与已创建的应用名称重复。创建成功后，当前应用将会自动生成对应的endpoint地址。
记录生成的endpoint地址，后续初始化SDK时需要使用。

安装SDK

在您的Electron项目根目录下执行以下命令安装SDK：

npm install @arms/rum-electron

说明：electron为SDK的peerDependency，版本需 >= 28.0.0。如果项目中尚未安装electron，需要一并安装。

初始化SDK

在主进程入口文件中（如main.ts），在app.ready事件触发之前调用init()：

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

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',  // 替换为控制台获取的endpoint地址env: 'prod',                  // 环境：'prod' | 'gray' | 'pre' | 'daily' | 'local'version: '1.0.0',             // 应用版本号
});

重要

init()必须在Electron的app.ready事件触发之前调用。SDK需要在应用启动早期注册自定义协议（rum-event://）和preload脚本，这些操作必须在app.ready之前完成，否则将无法正常工作。

初始化完成后，SDK默认行为如下：

autoInject默认为true，SDK会自动将Browser SDK注入所有BrowserWindow的渲染进程。
渲染进程代码无需任何修改，无需添加preload脚本。
数据通过IPC通道统一在主进程上报。

验证接入

完成初始化后，启动您的Electron应用并进行一些操作（如页面切换、发起网络请求等）。您可以通过beforeReport回调在主进程控制台查看上报数据：

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

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

等待约1-2分钟后，在ARMS控制台的用户体验监控 > 应用列表中查看您的应用，确认有数据上报。

您可以在控制台中查看：

实时概览：PV、UV、JS错误数、API请求数等核心指标。
会话详情：用户会话轨迹、页面浏览路径。
异常分析：JS错误堆栈、崩溃分析、错误分布。
性能分析：API耗时分布、慢接口TOP榜。

高级用法

手动注入模式

如果您不希望SDK自动注入Browser SDK到所有渲染进程，可以设置autoInject: false，然后在需要监控的渲染进程中手动初始化。

主进程初始化：

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

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  autoInject: false,  // 禁用自动注入
});

渲染进程手动初始化：

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

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

手动注入模式下，只有显式调用@arms/rum-electron/browser初始化的渲染进程才会采集数据。适用于需要精细控制监控范围的场景。

自定义Partition支持

如果您的BrowserWindow使用了自定义partition配置，需要确保SDK为该partition注册了preload脚本。SDK提供了两种方式支持自定义partition：

方式一：init时配置partition

在初始化时传入partition参数，SDK会自动为该partition注册preload脚本：

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

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  partition: 'persist:main',  // 与BrowserWindow的partition保持一致
});

const win = new BrowserWindow({
  webPreferences: {
    partition: 'persist:main',  // 必须与init中的partition一致
  },
});

方式二：init后动态注册

在SDK初始化后，通过registerSession()为其他partition动态注册preload脚本：

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

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
}).then(() => {
  // 为其他partition动态注册
  armsRum.registerSession('persist:other');
});

在创建对应BrowserWindow之前调用registerSession()，以确保首次页面加载即生效。

启用SPA路由追踪

对于使用SPA（单页应用）路由的Electron渲染进程，可以启用SPA路由追踪以自动采集路由切换事件：

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

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

spaMode支持以下取值：

false：禁用SPA路由追踪（默认行为，仅追踪完整页面加载）。
true或'auto'：自动检测路由模式，优先hash后pathname。
'hash'：Hash路由模式（如React HashRouter）。
'history'：History API路由模式（如React BrowserRouter）。

启用链路追踪

通过配置tracing，可以启用分布式链路追踪，将前端请求与后端服务关联：

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

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  tracing: {
    enable: true,
    sample: 0.1,              // 10%采样率propagatorTypes: ['tracecontext', 'b3'],  // 链路传播协议allowedUrls: [
      { match: 'https://api.example.com', sample: 0.5 },  // 仅追踪指定URL，50%采样
    ],
  },
});

propagatorTypes支持tracecontext、b3、b3multi、jaeger四种协议。allowedUrls用于指定需要追踪的请求URL，未配置时将追踪所有请求。