Electron 快速开始¶

本文适用于应用本身是 Electron、由 Adapter 管理 Native SDK 的全量模式（managed）。仅需 Browser 独立上报或已有原生宿主时，先阅读接入方式选择。

准备与安装¶

准备目标平台的原生 RUM 应用 ID，以及可用的 DataKit 地址，或 DataWay 地址和 Client Token。它们在 Main Process 中配置；Native SDK 管理 Session、采样、用户、全局上下文、持久化和上传。Renderer 的占位配置不用于创建独立 Web 应用，也不承担上传职责。

安装需要 Node.js 18+。Windows 还需要与目标架构匹配的 Microsoft Visual C++ v14 Redistributable 和 Windows Universal CRT；Electron 与平台要求见支持范围。

在已有 Electron 项目中安装：

npm install @cloudcare/electron-native-adapter@alpha @cloudcare/browser-rum

postinstall 会下载并校验当前平台的配套 Native Runtime，不需要本地编译。保留安装脚本；本例不设置 native.directory。离线、自定义运行时和原生宿主接入见平台专题，不需要在首次接入时安装 vcpkg。

Main：初始化并登记窗口¶

将以下代码合并到应用的 CommonJS 主进程入口，例如 main.cjs。先等待 Electron 就绪和 bootstrap() 完成，再创建并加载窗口。

const electron = require("electron");
const { app, BrowserWindow } = electron;
const { bootstrap } = require("@cloudcare/electron-native-adapter");

let client;
let stopping = false;
let stopped = false;

// Electron 不会自动等待异步退出回调。
app.on("before-quit", (event) => {
  if (!client || stopped) return;
  event.preventDefault();
  if (stopping) return;
  stopping = true;
  client.stop().catch(console.error).finally(() => {
    stopped = true;
    app.quit();
  });
});

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: "managed",
      settings: {
        applicationId: "<RUM 应用 ID>",
        datakitUrl: "http://127.0.0.1:9529",
        service: "electron-desktop",
        environment: "prod",
        version: app.getVersion(),
      },
    },
    autoAttach: true,
    onError: console.error,
  });

  const window = new BrowserWindow({
    webPreferences: {
      preload: require.resolve(
        "@cloudcare/electron-native-adapter/preload/standalone",
      ),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  });
  await window.loadFile("index.html");
}).catch((error) => {
  console.error(error);
  app.quit();
});

app.on("window-all-closed", () => app.quit());

本例所有窗口均可信，因此使用 autoAttach: true。如果只监测部分窗口，使用手动窗口登记。index.html 应替换为应用实际构建生成的页面路径。

使用 DataWay 时，将 datakitUrl 替换为 datawayUrl 和 clientToken，仅在 Main 配置真实凭据。macOS 实际上报的应用版本由应用打包信息决定。

Preload：建立页面桥接¶

上面的 preload/standalone 已安装 window.FTWebViewJavascriptBridge，无需额外创建 Preload 文件。它必须在 Browser RUM 初始化前执行。应用已有业务 Preload 时，按合并 Preload接入安装函数并打包为单一文件。

Renderer：初始化页面采集¶

将以下代码放入现有前端构建工具处理的 Renderer 入口，确保 index.html 加载该入口的构建产物。不要把含 npm 裸模块导入的源文件直接作为沙箱页面脚本加载。

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

if (typeof window.FTWebViewJavascriptBridge?.sendEvent !== "function") {
  throw new Error("Electron Native Bridge 尚未就绪");
}

datafluxRum.init({
  applicationId: "native-bridge",
  datakitOrigin: "http://127.0.0.1",
  service: "electron-renderer",
  env: "prod",
  sessionSampleRate: 100,
  trackUserInteractions: true,
});

applicationId 和 datakitOrigin 保持占位值即可。Bridge 生效时 Browser SDK 将事件交给 Native，不向这个地址发送 RUM 请求。Bridge 未就绪时先修复 Preload 和窗口登记，不要移除检查后继续初始化，也不要混入 Browser 独立上报的真实应用 ID、Token 或会话持久化配置。

每个待采集页面都执行一次初始化；页面刷新后由该页面入口重新初始化。真实采样由 Native 控制，Browser 保持 100%，避免二次降低采样率。

退出清理¶

Main 示例已经在 before-quit 中等待 client.stop()，清理结束后再继续退出。Windows 应关闭 Adapter 启动的 Bridge EXE，macOS 应关闭由 Adapter 初始化的 Native SDK。不要使用直接终止进程的方式代替正常退出；stop() 完成也不代表离线队列已经全部送达服务端。

验证上报¶

开发运行：使用项目现有启动命令运行应用，确认 Main 没有初始化错误，Renderer 中存在 Bridge，Network 中没有 Browser RUM 直传请求。
页面事件：访问页面、点击按钮、发送一次请求并触发测试错误，在观测云中确认 View、Action、Resource、Error 使用 Native 配置的应用 ID；Long Task 需触发超过采集阈值的任务。
多窗口：创建第二个窗口，加载相同 Preload 并在该页面初始化 Browser RUM，确认两个窗口均有数据。在 Native 未切换 Session 的条件下检查会话关联；采用手动登记时检查未登记窗口不产生 Bridge 数据。
退出：正常关闭应用，确认 client.stop() 完成且无清理错误；Windows 检查本应用启动的 Bridge EXE 已退出。
打包运行：按 Windows 打包或 macOS 打包与签名交付完整运行时到 ASAR 外，再运行打包产物，重复以上检查。验证不依赖开发机的绝对路径。

接入完成后，再按公共配置调整采样、窗口和可选采集能力。