Electron¶

Windows RUM SDK 接入 Electron 时采用原生 Bridge 模式，整体方式与 Android WebView 接入一致：Renderer 中的 Browser RUM SDK 只负责页面数据采集和序列化，Electron Main Process 将 Bridge 数据交给 Windows Native Core。真实应用 ID、会话、采样、全局上下文、SDK 标识、持久化队列和上传全部由原生端负责。

该模式不同于 Web RUM 的 Electron 独立接入。独立接入由 Browser RUM 直接管理 Session 并上传；Windows SDK 集成方不要在 Renderer 中重复配置真实上报信息或直传数据。

数据流¶

Electron Renderer
  @cloudcare/browser-rum 采集器
          |
          | FTWebViewJavascriptBridge.sendEvent(JSON)
          v
安全 Preload -> 白名单 IPC -> Electron Main Process
          |
          v
Windows Native Core
  原生会话 / 采样 / 上下文 / 持久化 / 上传

Browser RUM 会通过 Bridge 发送两种消息：

• { name: "rum", data: ... }：View、Action、Resource、Error 和 Long Task；
• { name: "session_replay", data: ..., view: { id: ... } }：实验性 Session Replay 的 rrweb record。

安装 Browser RUM¶

npm install @cloudcare/browser-rum

Browser RUM 只安装在需要采集的 Renderer 代码中。不要在 Main Process 初始化 Browser RUM，也不要在 Renderer 初始化 Guance.Rum.Windows。

在 Preload 建立 Bridge¶

Bridge 必须在页面 JavaScript 执行前建立。保持 contextIsolation: true、nodeIntegration: false 和 sandbox: true：

const { contextBridge, ipcRenderer } = require("electron");

const replayEnabled = process.argv.some((argument) =>
  argument.startsWith("--guance-rum-replay="),
);
const MAX_EVENT_BYTES = 1024 * 1024;

contextBridge.exposeInMainWorld(
  "FTWebViewJavascriptBridge",
  Object.freeze({
    getCapabilities: () => JSON.stringify(replayEnabled ? ["records"] : []),
    getPrivacyLevel: () => "mask",
    getAllowedWebViewHosts: () => null,
    sendEvent: (serializedEvent) => {
      if (
        typeof serializedEvent === "string" &&
        Buffer.byteLength(serializedEvent, "utf8") <= MAX_EVENT_BYTES
      ) {
        ipcRenderer.send("rum:browser-event", serializedEvent);
      }
    },
  }),
);

Bridge 方法均为同步方法：

• getCapabilities()：原生端允许实验性 Replay 时返回 ["records"]，否则返回 []；
• getPrivacyLevel()：返回 allow、mask-user-input 或 mask；
• getAllowedWebViewHosts()：可返回允许接入的域名列表；若 Electron Main Process 已严格限制页面来源，也可返回 null；
• sendEvent()：只把序列化消息发送到固定 IPC Channel，不能向 Renderer 暴露任意原生调用。

Renderer 最小初始化¶

仅建立 Bridge 不会自动启动页面采集。每个需要监控的 Renderer 仍需加载 Browser RUM 并调用一次 init()，但这里是采集器初始化，不是独立 Web RUM 的完整上报初始化：

import { datafluxRum } from "@cloudcare/browser-rum";

datafluxRum.init({
  // 当前 Browser SDK 在选择 Bridge 模式前仍会校验这些参数。
  // 它们只是占位值，不是真实应用 ID 或上报地址。
  applicationId: "00000000-aaaa-0000-aaaa-000000000000",
  datakitOrigin: "http://127.0.0.1",

  sessionSampleRate: 100,
  trackUserInteractions: true,
  trackViewsManually: true,
  actionNameAttribute: "data-guance-action-name",
  compressIntakeRequests: false,
});

datafluxRum.startView({ name: "electron.main" });

当 FTWebViewJavascriptBridge 可用时，Browser RUM 会使用 Bridge Session Stub，不启动 Browser HTTP Batch，并把采集结果序列化后交给原生端。Renderer 配置中不要包含以下真实值：

• RUM Application ID；
• Client Token；
• Dataway 或 DataKit 地址；
• 原生 Session ID 和采样决策；
• sdk_name、原生全局 Context 和可信用户信息；
• 持久化队列和重试策略。

这些配置由 Windows Native Core 统一生成或读取。Renderer 也不需要配置 sessionPersistence: "local-storage" 来承担权威 Session 持久化。

Main Process 与原生端¶

Main Process 需要完成以下工作：

1. 只接受已注册 BrowserWindow 主 Frame 发出的固定 IPC Channel；
2. 校验消息大小、JSON 结构、消息名称和 RUM Measurement；
3. 使用原生可信配置覆盖 Renderer 传入的应用 ID、Session、Service、Env、Version、SDK 标识和用户字段；
4. 将 RUM 数据写入 Windows Native Core 的 RUM 队列；
5. 将 Replay record 与 Browser view.id 一起写入 Native Replay 分段和队列；
6. 由 Native Core 统一执行 Dataway/DataKit 上传、失败重试和诊断统计。

原生事件使用 Windows SDK 身份，例如 sdk_name=df_windows_rum_sdk；这不是 Renderer 伪造字段，而是 Native Core 对 Bridge 数据完成可信接管后的 SDK 身份。

开启实验性 Session Replay¶

原生配置启用 Replay 后，Bridge 返回 records 能力，Renderer 再启动录制：

datafluxRum.startSessionReplayRecording();

关闭时调用：

datafluxRum.stopSessionReplayRecording();

Replay 的启用状态、采样率和隐私级别必须来自原生配置。Browser 侧仅依据 Bridge 能力进行 DOM、输入、指针、滚动和 Canvas 等 record 采集，不负责 Replay Session、持久化或上传。

多窗口与远程页面¶

• 每个需要监控的 BrowserWindow、BrowserView 或 <webview> 都需要安装 Bridge，并各自执行一次 Browser RUM 最小初始化；
• Main Process 必须维护可信 Renderer 白名单，不能接受任意 WebContents 发来的数据；
• 远程 HTTP(S) 页面也可以使用同一 Bridge 模式，但必须限制导航、弹窗、权限和允许域名；
• 本地 file:// 与远程 HTTP(S) 页面不依赖各自的 Browser LocalStorage Session，最终统一使用原生 Session 和 Context。

验证¶

1. Renderer DevTools Network 中不应出现 RUM 或 Replay 直传请求；
2. 触发 View、Action、Resource、Error 和 Long Task，确认数据进入观测云；
3. 确认数据使用原生应用 ID、原生 Session ID 和 sdk_name=df_windows_rum_sdk；
4. Replay 关闭时，getCapabilities() 返回 []；
5. Replay 开启时，getCapabilities() 返回 ["records"]，并验证输入隐私、动态 DOM、弹层、滚动和 Canvas 场景；
6. 通过原生诊断确认 RUM/Replay 队列、上传成功、重试和最终失败计数。

Windows SDK 仓库中的 Electron Sample 提供了完整的 Preload、IPC、Native Host、RUM 和实验性 Replay 验证实现。