Electron 配置与生命周期¶

本文是 Windows 和 macOS Native Bridge 共用的配置说明。首次接入使用 managed 快速开始；模式选择见应用接入。平台宿主初始化、运行时安装和打包仍分别见 Windows和 macOS。

Main 配置¶

managed 在 bootstrap() 的 native.settings 中配置应用和上传参数。external 由原生宿主配置 Native SDK，不传入 native.settings。

Windows 可保留 0.1 等小数精度；默认配套的 macOS Native Runtime 使用整数百分比，启用的采集功能使用新版字段传入小数时，Adapter 会报错，不会四舍五入。自定义 macOS Runtime 的小数采样支持取决于其实际能力，普通采样与 Replay 分别检查。旧采样字段自 Adapter 0.1.0-alpha.4 起废弃，仍兼容原有单位及既有 macOS 舍入行为。同一配置同时设置新旧字段时，以新字段为准，包括显式设置 0。

macOS 实际上报的应用版本由应用打包信息决定。traceEnabled 只配置 Native Trace，不会自动为 Renderer 的请求注入 Trace Header。

用户绑定和全局属性通过 Native SDK 的能力统一管理，见 Windows 自定义标签和 Apple SDK 自定义标签。Adapter Client 不提供与 Browser setUser() 对等的公共用户绑定接口；不要通过引用 Adapter 内部模块修改 Native 状态。

Preload¶

只使用 npm 包公开入口：Main 使用 @cloudcare/electron-native-adapter；无业务 Preload 时使用快速开始中的 preload/standalone；已有 Preload 时调用一次安装函数：

const {
  installElectronRumPreload,
} = require("@cloudcare/electron-native-adapter/preload/install");

installElectronRumPreload();

保持 contextIsolation: true、nodeIntegration: false 和 sandbox: true。沙箱 Preload 不能直接用普通 Node.js require() 加载 npm 包，需用应用的 bundler 合并上述代码及其依赖，并保留 electron 为外部依赖。例如已安装 esbuild 的项目可执行：

npx esbuild src/preload.cjs --bundle --platform=node --format=cjs --external:electron --outfile=dist/preload.cjs

将 webPreferences.preload 指向产物的绝对路径。独立 Preload 已可直接用于沙箱，不需要重复安装桥接。不要复制 Adapter 源码或直接引用未公开的 internal/、core/、platform/ 文件。

窗口管理¶

每个需要采集的窗口都必须加载 Preload，并在加载页面前登记。autoAttach 默认为 false；设置为 true 会登记已有和后续创建的窗口，适用于所有窗口均可信且需要采集的应用，不能代替 Preload。

只监测指定窗口时，在 bootstrap() 中保持 autoAttach: false，然后登记该窗口：

// client 为 bootstrap() 返回值，window 为已配置 Preload 的 BrowserWindow。
const detach = client.attachWindow(window);
await window.loadFile("index.html");
// 需要提前停止采集时调用 detach() 或 client.detachWindow(window)。

每个窗口单独登记；刷新和导航不需要重复登记。窗口销毁时 Adapter 自动移除登记。包含不可信页面的应用仅为目标窗口加载 Preload，并限制远程页面的导航、弹窗、权限和允许域名。

Renderer¶

managed 和 external 共用快速开始的 Renderer 初始化。每个页面在 Bridge 就绪后初始化 Browser RUM，真实应用 ID、Session、采样和上传仍由 Native SDK 管理。Bridge 已存在不代表数据一定送达，还需检查 Main 传输错误和服务端接收结果。

页面日志¶

先开启 Native 日志能力：managed 设置 loggingEnabled: true；external 按 Windows 宿主或 macOS Logger配置。主进程通过 client.capabilities.log 检查实际能力，仅在启用该能力的页面初始化 Browser Logs；如通过业务 Preload 传递该状态，只暴露布尔值。

安装 @cloudcare/browser-logs（Bridge 接入要求 3.3.6 或更高版本）后，在已完成 RUM Bridge 接入的 Renderer 中使用：

import { datafluxLogs } from "@cloudcare/browser-logs";

datafluxLogs.init({
  datakitOrigin: "http://127.0.0.1",
  sessionSampleRate: 100,
  forwardErrorsToLogs: true,
  forwardConsoleLogs: ["error", "warn"],
});

Browser 保持 100%，实际日志采样由 Native 控制。关闭 Native 日志能力时，不要仍在页面独立初始化 Logs 作为备用上传路径。

Session Replay¶

Replay 默认关闭，必须同时满足 Native SDK 配置、对应组件和 Bridge 实际能力要求。先完成 Windows 可选 Replay 运行时或 macOS Replay 配置，再在 datafluxRum.init() 后检查能力：

const capabilities = JSON.parse(
  window.FTWebViewJavascriptBridge.getCapabilities(),
);
if (capabilities.includes("records")) {
  datafluxRum.startSessionReplayRecording();
}

records 表示 Native 提供回放能力，不代表当前 Session 必然命中采样。不要照搬 Browser 独立录制流程强制开启 Replay。主进程也可检查 client.capabilities.replay；组件缺失、关闭与开启后的验证按平台说明执行。

生命周期与诊断¶

bootstrap() 返回 Client，提供 capabilities、attachWindow()、detachWindow()、updateWindow()、transportState 和幂等的 stop()。通过 onError 接收异步传输和窗口处理错误，transportState 用于检查可写状态、背压和传输失败。

正常退出时必须等待 stop()，完整异步退出处理见快速开始 Main 示例。停止采集不是“全部离线数据已经上传”的确认。Windows 连接超时、Bridge 输出和启动 Action 等参数见平台配置。macOS 不提供 Windows 的自动启动 Action；混合模式的回放窗口可见性边界见 macOS Replay。