Electron 监测¶

本页保留 Windows 原生宿主、运行时、Replay 和打包说明。首次接入请从 Electron 应用接入选择方案；应用主体为 Electron 时先完成 managed 快速开始。

Windows SDK 通过 Native Bridge 接入 Electron：Renderer 中的 Browser RUM 和 Browser Logs 负责采集页面数据，Electron Main Process 将数据交给 Windows Native Core，由 Native Core 统一管理应用 ID、Session、采样、全局上下文、持久化队列和上传。

根据 Native SDK 的初始化所有者选择一种模式：

两种模式不能同时使用。页面侧共用相同的 Preload、attachWindow() 和 Renderer 初始化方式。

该方式不同于 Web RUM 的 Electron 独立接入。Windows SDK 集成中，Renderer 不直接上传数据，也不配置真实应用 ID、上报地址或 Client Token。

数据流如下：

Electron Renderer
  @cloudcare/browser-rum / @cloudcare/browser-logs 采集器
          |
          | FTWebViewJavascriptBridge.sendEvent(JSON)
          v
安全 Preload -> 白名单 IPC -> Electron Main Process
          |
          v
Windows Native Core（由 C++ 宿主或 Bridge EXE 初始化）
  原生 RUM / Log / 会话 / 采样 / 上下文 / 持久化 / 上传

集成 Electron¶

安装依赖¶

应用主体为 Electron 时，按公共快速开始安装依赖并接入 Main、Preload 和 Renderer。Electron 版本要求见支持范围。

npm 安装和运行时安装器要求 Node.js 18+；打包后的应用用户无需另行安装 Node.js。Windows 支持 x64、x86（Electron/Node.js 中为 ia32）和 arm64，需要安装与运行时架构匹配的 Microsoft Visual C++ v14 Redistributable 和 Windows Universal CRT。

发布的 npm 包本身不内置 Native 二进制，但 postinstall 会按平台和架构下载并校验 Native Runtime，无需本地编译。全量模式默认自动定位该运行时，不需要先安装 vcpkg。Adapter 同时支持 macOS；本页介绍 Windows Native Bridge 接入。

仅使用混合模式时，可在安装前设置 PowerShell 环境变量 $env:GUANCE_NATIVE_SKIP_DOWNLOAD = "1"，跳过不使用的运行时下载；切换回全量模式安装前需清除此变量。

初始化 Native Bridge¶

全量模式¶

由 Electron Main Process 启动并管理 Bridge EXE，完整初始化与退出示例见 managed 快速开始。公共 native.settings 字段、采样单位及版本差异见 Main 配置。

Windows 需要自定义缓存目录时，可将 cachePath 设置为 path.join(app.getPath("userData"), "native-rum-cache")，其中 path 为 node:path 模块，app 为 Electron App。

其他可选配置：

退出清理和公共 Client API 见生命周期与诊断。startFullMode() 与 connectMixedMode() 仅保留早期版本兼容，新接入统一使用 bootstrap()。

Adapter 默认启用 enableAppLaunch，会结合 Electron 应用生命周期、可信窗口首帧和 Browser View 上下文自动生成 launch_cold、launch_hot Action；不需要自动启动 Action 时设置为 false。为保证冷启动关联首个 Browser View，应尽早启动或连接 Bridge，并在创建窗口后立即调用 attachWindow()。

混合模式¶

C++ 宿主先初始化 Windows SDK，再将 Bridge Server 绑定到已有的 guance_sdk_handle：

guance_sdk_config_v2 config{};
guance_sdk_config_v2_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-application-id>";
config.session_sampling_rate = 100.0f; // vcpkg 0.1.0-alpha.9 起支持
guance_sdk_handle sdk = guance_sdk_init_v2(&config);

guance_electron_bridge_server_options options{};
guance_electron_bridge_server_options_init(&options);
options.pipe_name = "my-app-rum";
options.logging_enabled = 1;
options.session_replay_enabled = 0;
options.replay_privacy_level = "mask";

guance_electron_bridge_server_handle bridge =
    guance_electron_bridge_server_start(sdk, &options);

// 应用退出时先停止 Bridge Server，再关闭 SDK。
guance_electron_bridge_server_stop(bridge);
guance_sdk_shutdown(sdk);

Electron Main Process 连接同名 named pipe：

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

const rumBridge = await bootstrap({
  electron,
  native: {
    mode: "external",
    pipeName: "my-app-rum",
  },
  enableAppLaunch: true,
});

混合模式下：

• 不要启动 guance_windows_electron_bridge.exe，否则会创建第二个 SDK Handle；
• Electron 不再传入应用 ID、DataKit/Dataway、缓存或上传配置；
• C++ 宿主必须保证 SDK Handle 的生命周期长于 Bridge Server；
• 采集 Browser Log 时，需要同时启用 Native 自定义日志，并将 logging_enabled 设为 1。

接入 Preload 与窗口¶

按 公共 Preload 配置安装桥接，再按窗口管理在加载页面前登记窗口；managed 与 external 共用此流程。

初始化 Renderer¶

按公共 Renderer 接入初始化页面 RUM、可选日志和 Replay。真实应用 ID、上传地址和凭据由 Native 管理。

安装可选 Replay 运行时¶

全量模式在开发或构建阶段安装 Replay 补充包，不在应用运行时下载 DLL。在应用根目录运行：

npx guance-electron-native --sdk-version vcpkg_0.1.0-alpha.10 --target win32-x64 --with-replay

CLI 输出的运行时目录在开发时传给 native.directory，打包时传给 stageWindowsRuntime() 的 nativeDirectory；打包后使用 resources/native 自动定位。x86、arm64 应分别选择 win32-x86、win32-arm64。也可在 npm 安装前设置 $env:GUANCE_NATIVE_INSTALL_REPLAY = "1"，让 postinstall 将补充组件安装到 npm 包的运行时目录，随后按默认方式定位和打包。

离线安装需同时准备基础与 Replay 归档及各自的 .sha256 文件：

npx guance-electron-native --sdk-version vcpkg_0.1.0-alpha.10 --target win32-x64 --runtime-archive C:/sdk/runtime.tar.gz --replay-archive C:/sdk/replay.tar.gz

安装器会校验两个清单的 SDK 版本、架构和文件哈希，将 guance_windows_replay.dll 放到基础 DLL 同一目录。安装完成后仍需设置 replayEnabled: true。Replay 缺失或无法加载时，普通 RUM 继续工作，Renderer 不获得 records 能力。

混合模式的组件由 C++ 宿主通过 vcpkg replay Feature 提供，DLL 与宿主的基础 SDK 同目录；Electron Adapter 根据 Bridge Server 握手中的实际能力决定是否转发 Replay。详见可选组件安装。

打包资源¶

全量模式应在应用签名前调用公开的打包辅助函数，把完整运行时复制到 ASAR 之外：

const { stageWindowsRuntime } = require(
  "@cloudcare/electron-native-adapter/packaging/windows",
);

stageWindowsRuntime({
  resourcesDirectory: "release/MyApp-win32-x64/resources",
  arch: "x64",
});

辅助函数默认定位 npm 包内已安装的运行时，复制到 resources/native；目标目录必须为空。打包后的 managed 模式会自动定位该目录，无需设置 native.directory。Native EXE、DLL 和 manifest 等资源应完整保留，不能放入 app.asar。

已安装 Replay 时，stageWindowsRuntime() 会同时校验并复制补充 DLL 和 replay-manifest.json。基础运行时与 Replay 补充组件必须保持相同版本和架构。

跨架构打包时，先安装目标运行时，再显式传入目标 arch。Windows 支持 x64、x86 / ia32、arm64。CLI 安装的运行时须通过辅助函数的 nativeDirectory 指定。

手动使用 vcpkg 工具目录时，也可继续通过 electron-builder 的 extraResources 复制，并使用下文 vcpkg 小节的 sdkDirectory 指定资源位置：

{
  "build": {
    "extraResources": [
      {
        "from": "vcpkg_installed/x64-windows/tools/guance-windows-native",
        "to": "guance-windows-native"
      }
    ]
  }
}

全量模式必须交付同一 SDK 版本的 guance_windows_electron_bridge.exe 和相邻的 guance_windows_native.dll，同时由应用打包工具携带 @cloudcare/electron-native-adapter。混合模式不需要复制 vcpkg 工具目录；Native DLL 仍由 C++ 宿主原有的部署流程交付，JavaScript Adapter 仍由 npm 依赖提供。不要依赖当前工作目录或开发机绝对路径定位资源。

可选：由 vcpkg 提供 Native Runtime¶

宿主拥有 Native SDK，或需要自行构建运行时时，按照快速开始配置 SDK vcpkg 注册表。JavaScript Adapter 仍由 npm 单独安装。手动提供全量模式运行时时启用 electron-bridge：

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "default-features": false,
      "features": ["electron-bridge"]
    }
  ]
}

混合模式安装基础 Native 包；使用 Replay 时，在该依赖中添加 "features": ["replay"]。无需启用旧 electron-bridge Feature：

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "default-features": false
    }
  ]
}

在 vcpkg.json 所在目录执行：

vcpkg install --triplet x64-windows

以上 vcpkg 命令以 x64 为例。手动使用 vcpkg 工具目录时，将下面的 sdkDirectory 传入 native.directory；默认 npm 下载流程无需配置此项：

const path = require("node:path");
const { app } = require("electron");

const sdkDirectory = app.isPackaged
  ? path.join(process.resourcesPath, "guance-windows-native")
  : path.resolve(
      __dirname,
      "../../../vcpkg_installed/x64-windows/tools/guance-windows-native",
    );

开发目录的相对层级应按应用结构调整，不要依赖当前工作目录或写死开发机绝对路径。

自定义与离线运行时安装¶

若 npm 安装时使用了 --ignore-scripts，或需要其他目标架构，可在应用根目录运行：

npx guance-electron-native --sdk-version <sdk-tag> --target <target>

Windows 目标为 win32-x64、win32-x86、win32-arm64；macOS 为 darwin-universal。<sdk-tag> 使用 Native SDK Release 的完整标签，保留 vcpkg_、nuget_ 或 v 等已有前缀；标签下必须存在对应运行时资产。

离线安装需要 SDK .tar.gz 和相邻的 .tar.gz.sha256 校验文件：

npx guance-electron-native --sdk-version <sdk-tag> --target <target> --runtime-archive C:/sdk/runtime.tar.gz

CLI 将运行时安装到应用根目录下。开发时把输出目录传给 native.directory，打包时传给 stageWindowsRuntime() 的 nativeDirectory；打包后移除开发目录配置，使用自动定位的 resources/native。

npm postinstall 可使用以下环境变量（PowerShell 使用 $env:变量名 = "值" 设置）：

压缩包必须与指定 SDK 版本和架构匹配。仅提供离线 Native Runtime 不代表 npm 完全离线；还需要提前准备 npm 包及其依赖缓存。私有源码 checkout 会跳过自动下载，本地 file: 依赖联调时需自行准备运行时。

集成边界¶

• Main Process 只使用 @cloudcare/electron-native-adapter 导出的公开接口，不自行注册 SDK 内部 IPC Channel；
• 不要将应用 ID、Client Token、DataKit/Dataway 地址、原生 Session 或完整 Native 配置暴露给 Renderer；
• Main Process 只登记可信的 webContents。远程页面还需要限制导航、弹窗、权限和允许域名；
• 全量模式通过 native.settings 配置 Native Trace，混合模式由宿主配置。Adapter 不向 Renderer 注入 Trace 配置，也不因此自动为页面请求添加 Trace Header；
• Renderer JavaScript Error 和 Long Task 由 Browser RUM 采集；unresponsive、render-process-gone 和 Main Process Crash 不由 Bridge 自动上报，如有需要应单独接入 Electron crashReporter 或其他 Crashpad 服务。

验证集成¶

1. 在 Renderer DevTools Network 中确认没有 RUM 或 Log 直传请求；
2. 触发 View、Action、Resource、Error、Long Task 和一条 Browser Log，在控制台确认数据；
3. 确认数据使用 Native 配置中的应用 ID、Session ID 和 sdk_name=df_windows_rum_sdk；
4. 确认 Browser Log 的 warn 状态在 Native Log 中显示为 warning，且自定义属性被保留；
5. Replay 关闭或组件缺失时，确认 getCapabilities() 不包含 records；组件安装并开启后，确认录制数据正常上报；
6. 混合模式关闭 Electron 页面后，确认 C++ SDK 仍在运行；全量模式退出应用后，确认 Bridge EXE 正常关闭。

可参考 Windows SDK 仓库中的 Electron Native Adapter Consumer Acceptance 和 Electron Sample 完成验收。本地联调可以使用 npm file: 依赖；正式应用使用发布包，并通过应用的 lockfile 管理实际安装版本。