macOS Electron 监测¶

macOS SDK 通过 Guance Electron Native Adapter 接入 Electron：Renderer 中的 Browser RUM 和 Browser Logs 负责采集页面访问、用户操作、请求、错误、Long Task 和页面日志，Electron Main Process 将数据交给 macOS Native SDK，统一管理原生 RUM 应用、会话、采样和上传。需要会话回放时，按下文同时配置 Native SDK 和页面录制。

根据应用结构选择一种模式，同一个 Electron 进程只使用一种模式：

两种模式共用相同的 Preload、窗口登记和 Renderer 初始化方式。Renderer 不配置真实 RUM 应用 ID、上传地址或 Client Token。选择模式后，配置 Preload 并初始化页面 SDK。如果只需要将 Electron 页面作为独立 Web 应用监测，请参考 Web RUM 的 Electron 接入。

数据流如下：

全量模式（managed）
Electron Renderer
  Browser SDK -> 安全 Preload -> Electron Main Process
                                      |
                                      v
                      Node Addon（内含 Native SDK）
                                      |
                                      v
                                     上传

混合模式（external）
Electron Renderer
  Browser SDK -> 安全 Preload -> Electron Main Process
                                      |
                                      | 受认证的 Unix Domain Socket
                                      v
                         macOS Native 主程序
                         Native SDK -> 上传

集成 Electron¶

安装依赖¶

• 安装 Adapter 和 Native 运行时需要 Node.js 18 或更高版本，并能访问 npm Registry 和 Native SDK 的 GitHub Release；离线环境需提前准备 npm 包、依赖和 Native 运行时压缩包；
• 全量模式使用预编译的 Universal 运行时，安装时不编译 Native SDK，无需为此安装 Git、Swift 或 Xcode Command Line Tools；应用打包、签名和公证仍需相应的 macOS 工具链；
• 混合模式需要先在 macOS 原生主程序中接入 Native SDK。下文的 configureElectronProcess 接入方式从 Native SDK 1.6.8-alpha.7 开始提供，参见原生主程序集成。

Guance Electron Native Adapter 支持 Electron 22.x（不低于 22.3.27）和 43.x。

全量模式通过 npm 安装：

npm install @cloudcare/electron-native-adapter

已发布的 npm 包会在安装时自动下载配套版本的 macOS Universal 运行时，并校验版本、架构和文件完整性，无需再执行构建命令。不要使用 --ignore-scripts 跳过安装脚本；如已跳过，可按下文显式安装运行时。

仅使用混合模式时，由原生主程序提供 Native SDK，安装 Adapter 时跳过不需要的运行时下载：

GUANCE_NATIVE_SKIP_DOWNLOAD=1 npm install @cloudcare/electron-native-adapter

Renderer 安装 Browser SDK：

npm install @cloudcare/browser-rum

如果需要采集页面日志，再安装 Browser Logs：

npm install @cloudcare/browser-logs

安装后，按采集页面日志完成配置。

指定或离线安装全量模式 Native 运行时¶

使用 npm 自动安装的运行时时，开发阶段无需设置 native.directory，Adapter 会从自身安装目录中查找运行时。npm 包与 Native SDK 的版本号相互独立，配套的 Native SDK 版本由 npm 包固定，不要求两者版本号相同。

如需指定其他 Native SDK 版本，在 Electron 应用项目根目录执行以下命令，将 <SDK_VERSION> 替换为包含 Electron 运行时资产的 Native SDK Release tag：

npx guance-electron-native --sdk-version '<SDK_VERSION>'

该命令下载预编译的 Universal 运行时，同时包含 arm64 和 x86_64，不提供单架构源码构建选项。安装器会校验压缩包、SDK 版本、架构和文件哈希。

离线安装时，提前准备同一 Release 中的 guance-electron-runtime-<SDK_VERSION>-darwin-universal.tar.gz 及其同名 .sha256 文件，将两者放在同一目录：

npx guance-electron-native --sdk-version '<SDK_VERSION>' \
  --runtime-archive '/absolute/path/guance-electron-runtime-<SDK_VERSION>-darwin-universal.tar.gz'

离线命令执行前需已安装 Adapter 及其 npm 依赖，否则 npx 自身仍可能访问 npm。也可以在 npm 安装时传入本地运行时压缩包：

GUANCE_NATIVE_RUNTIME_ARCHIVE='/absolute/path/runtime.tar.gz' \
  npm install @cloudcare/electron-native-adapter

本地压缩包优先于网络下载，其版本须与本次安装选择的 Native SDK 版本一致。npm 安装时可通过 GUANCE_NATIVE_SDK_VERSION 覆盖配套版本；显式 CLI 安装则使用 --sdk-version。更换版本后，需运行应用确认数据正常上报。

npm 自动安装的运行时位于 node_modules/@cloudcare/electron-native-adapter/.cloudcare/native/darwin/runtime。显式 CLI 安装则输出到应用项目的 .cloudcare/native/darwin/runtime，此时需将 native.directory 设置为该目录的绝对路径。建议将项目中的 .cloudcare/ 加入 Git 忽略规则。

打包时请将完整的 runtime 目录一起复制到应用资源目录中，具体配置见打包资源。

初始化 Native Bridge¶

混合模式¶

混合模式使用 native.mode: 'external'，需要先在 macOS 原生主程序中配置 SDK，再由原生主程序启动 Electron。应用信息、上传地址和采集选项统一在原生主程序中设置。

原生主程序集成¶

在原生主程序工程中通过 Swift Package Manager 添加 Native SDK，并将 <SDK_VERSION> 替换为使用的 SDK 版本号：

.package(
    url: "https://github.com/GuanceCloud/datakit-ios.git",
    exact: "<SDK_VERSION>"
)

将以下 Product 添加到 macOS 主程序 Target：

• GuanceSDK：Native SDK；
• GuanceElectronWebView：用于接入 Electron 页面数据；
• GuanceSessionReplay：仅在需要 Session Replay 时添加。

原生主程序先初始化 SDK 和 RUM。已接入 SDK 的应用保留原有初始化代码，并开启 enableTraceWebView，无需重复初始化：

#import <GuanceSDK/GuanceSDK.h>
#import <GuanceElectronWebView/GuanceElectronWebView.h>

FTSDKConfig *sdkConfig =
    [[FTSDKConfig alloc] initWithDatakitUrl:@"http://127.0.0.1:9529"];
[FTSDKAgent startWithConfigOptions:sdkConfig];

FTRumConfig *rumConfig =
    [[FTRumConfig alloc] initWithAppid:@"<RUM 应用 ID>"];
rumConfig.enableTraceWebView = YES;
rumConfig.enableTraceUserView = YES;
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];

如果需要 Session Replay，在启动 Electron 子进程前，使用 Native SDK 的 Session Replay API 初始化；如需页面日志，也应在此阶段完成原生 Logger 配置：

#import <GuanceSessionReplay/GuanceSessionReplay.h>

FTSessionReplayConfig *replayConfig = [[FTSessionReplayConfig alloc] init];
replayConfig.sampleRate = 100;
replayConfig.textAndInputPrivacy = FTTextAndInputPrivacyLevelMaskSensitiveInputs;
[[FTRumSessionReplay sharedInstance]
    startWithSessionReplayConfig:replayConfig];

配置并启动 Electron 子进程¶

创建 FTElectronBridgeServer 和 NSTask，在启动子进程前调用 configureElectronProcess:error:。该方法会自动启动 Bridge，并把连接参数合并到指定子进程的环境变量中，无需再单独调用 startWithError: 或手动设置 Bridge 环境变量。

在 AppDelegate 或负责子进程生命周期的对象中声明强引用属性：

@property (nonatomic, strong) FTElectronBridgeServer *electronBridgeServer;
@property (nonatomic, strong) NSTask *electronProcess;

完成前面的 Native SDK 配置后，执行以下启动代码：

self.electronBridgeServer = [[FTElectronBridgeServer alloc] init];
self.electronProcess = [[NSTask alloc] init];
self.electronProcess.executableURL =
    [NSURL fileURLWithPath:@"<Electron 可执行文件的绝对路径>"];
// 按应用结构设置启动参数，例如开发模式下的 Electron 项目路径。
// self.electronProcess.arguments = @[@"<Electron 项目的绝对路径>"];

NSError *error = nil;
if (![self.electronBridgeServer
        configureElectronProcess:self.electronProcess error:&error]) {
    [self.electronBridgeServer stop];
    // 在应用中处理 error，不要继续启动未配置成功的子进程。
    return;
}

// configureElectronProcess 只配置进程，不会自动启动 Electron。
if (![self.electronProcess launchAndReturnError:&error]) {
    [self.electronBridgeServer stop];
    // 在应用中处理启动失败。
    return;
}

Swift 中对应的调用为 try bridgeServer.configureElectronProcess(process)，然后执行 try process.run()。

如需传入业务环境变量，在调用 configureElectronProcess 前设置 electronProcess.environment。SDK 会保留已有的非 Bridge 参数；未设置时，继承 NSProcessInfo.processInfo.environment。该方法只修改指定子进程的启动环境，不修改原生主程序的环境；启动前可重复调用，但会用当前 Bridge 的值替换已有的 Bridge 参数。

以下连接参数由 Native Bridge 生成或提供，Adapter 默认从 Electron 主进程的 process.env 读取。用户不需要手动赋值或写入 .env.local，也不要把这些参数暴露给 Renderer：

使用不支持 configureElectronProcess 的旧 SDK 或自定义启动器时，仍可先调用 startWithError:，再将 environmentByAddingToEnvironment: 的返回值作为 Electron 的启动环境传入。仅启动 Bridge 并不会自动修改另一个进程的环境变量。

配置 Electron 主进程¶

在 Electron 创建或导航第一个窗口前，使用 bootstrap() 连接原生主程序。无需传入 native.settings 或手动读取连接参数：

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

let client

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: 'external',
    },
    autoAttach: true,
  })

  const window = new BrowserWindow({ /* 配置安全 Preload */ })
  await window.loadURL('https://example.com')
})

全量模式¶

全量模式使用 native.mode: 'managed'，在 Electron 主进程中配置应用信息和采集功能。

在创建或导航第一个 BrowserWindow 前调用 bootstrap()，并设置 native.mode: 'managed'：

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

let client

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: 'managed',
      // npm 自动安装的运行时无需设置 directory。
      // 如使用显式 CLI 安装，传入安装输出目录的绝对路径。
      settings: {
        applicationId: '<RUM 应用 ID>',
        datakitUrl: 'http://127.0.0.1:9529',
        service: 'electron-main',
        environment: 'prod',
        version: app.getVersion(),
        loggingEnabled: true,
        replayEnabled: true,
        replaySampleRate: 1,
        replayPrivacy: 'mask-user-input',
        traceEnabled: true,
      },
    },
    autoAttach: true,
  })

  const window = new BrowserWindow({
    webPreferences: {
      preload: require.resolve(
        '@cloudcare/electron-native-adapter/preload/standalone',
      ),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  })
  await window.loadURL('https://example.com')
})

在 native.settings 中配置应用信息、上传地址和需要开启的采集功能：

native.settings 中的所有采样率取值范围为 0..1，例如 1 表示 100%，0.2 表示 20%。replayPrivacy 用于设置回放中的隐私保护方式，allow、mask-user-input、mask 的保护程度依次增强，默认为 mask。

混合模式直接调用 Native SDK 配置 API 时，sampleRate 使用 0..100；Browser SDK 的 sessionSampleRate 和 sessionReplaySampleRate 也使用 0..100。不要把主进程 Adapter 配置中的 1 直接当作这些 API 的 100%。

如果使用 DataWay 上传，请用 datawayUrl 和 clientToken 替换示例中的 datakitUrl，并仅在主进程中配置 Token。

应用退出¶

退出前调用并等待 client.stop() 完成。

Electron 不会自动等待退出事件回调中的异步操作。应用需要完成清理后再退出时，可在主进程加入：

let stopping = false
let stopped = false

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()
  })
})

混合模式的原生主程序仍需按自身退出流程停止 Bridge 和 Native SDK。

接入 Preload 与窗口¶

集成时只使用 Adapter 的公开入口：

• @cloudcare/electron-native-adapter：Main Process 初始化入口；
• @cloudcare/electron-native-adapter/preload/standalone：没有现有 Preload 时直接使用；
• @cloudcare/electron-native-adapter/preload/install：将安装函数合并到业务 Preload。

不要直接引用或修改包内 internal/、core/ 或 platform/ 下的实现文件。每个需要采集的窗口都必须加载 Preload，并由 Main Process 通过 autoAttach 或 client.attachWindow() 登记。

如果应用没有自定义 Preload，可以直接使用 Adapter 提供的独立 Preload：

const window = new BrowserWindow({
  webPreferences: {
    preload: require.resolve(
      '@cloudcare/electron-native-adapter/preload/standalone',
    ),
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
})

如果应用已有 Preload，在业务 Preload 的源文件中调用一次安装函数：

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

installElectronRumPreload()

使用自定义 Preload 时，同样设置 contextIsolation: true、nodeIntegration: false 和 sandbox: true。使用 webpack、esbuild 等 bundler 将上述代码及 Adapter 依赖合并为一个 Preload bundle，保留 electron 为外部依赖，并将 webPreferences.preload 指向该产物的绝对路径。沙箱 Preload 不能直接通过普通 Node.js require() 加载 npm 包。

仓库中的 Electron 示例使用未打包的业务 Preload，因此设置了 sandbox: false；用于启用沙箱的应用时，需要先完成上述打包。独立 Preload 已可直接在沙箱中使用。

指定采集窗口¶

autoAttach 默认为 false。设置 autoAttach: true 后，Adapter 会自动接入启动前已存在的 BrowserWindow 和后续创建的窗口。页面刷新和跳转不需要重复调用。

如果只采集指定窗口，关闭自动接入，再在窗口加载页面前调用 client.attachWindow()：

const client = await bootstrap({
  electron,
  native: {
    mode: 'managed',
    // 如使用显式 CLI 安装，在此设置 directory。
    settings: nativeSettings,
  },
  autoAttach: false,
})

const window = new BrowserWindow({ /* ... */ })
client.attachWindow(window)
await window.loadURL('https://example.com')

关闭自动接入后，每个需要采集的窗口都必须单独调用 attachWindow()，并传入 BrowserWindow 实例。停止采集某个窗口时，调用 client.detachWindow(window)，也可以调用 attachWindow() 返回的移除函数；窗口销毁时 Adapter 会自动移除登记。

autoAttach: true 适用于所有窗口均可信且需要采集的应用。包含不需要采集或不可信页面的应用应设置为 false，只登记目标窗口，并仅为这些窗口加载 Guance Preload。

初始化 Renderer¶

两种模式都需要在每个待采集的页面中初始化 Browser RUM。主进程完成 bootstrap() 和窗口接入后，再加载页面并执行以下代码：

import { datafluxRum } from '@cloudcare/browser-rum'

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

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

在 Native Bridge 已生效的前提下，此处的 applicationId 和 datakitOrigin 用于满足 Browser SDK 的初始化配置，保持示例占位值即可，不需要另行申请 Web 应用或配置 Web 上传 Token。实际 RUM 应用、数据上传地址和凭据在 Electron 主进程（全量模式）或原生主程序（混合模式）中配置。不要在 Bridge 未就绪时使用占位配置初始化 Browser SDK。

采集用户操作¶

需要采集页面点击等用户操作时，按本节Renderer 初始化示例设置 trackUserInteractions: true。混合模式中，原生控件的自动操作采集通过原生主程序的 RUM 配置开启。

采集页面日志¶

需要采集页面日志时，先按接入模式开启日志采集：

• 全量模式：在 Electron 主进程的 native.settings 中设置 loggingEnabled: true，通过 loggingSampleRate 设置采样率。
• 混合模式：在 macOS 原生主程序中初始化 Logger 并开启 enableWebViewLog。

混合模式中，在原生主程序启动 Electron 前配置 Logger；如果已有 Logger 初始化代码，将以下选项合并到原有配置中：

FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.enableWebViewLog = YES;
loggerConfig.enableLinkRumData = YES;
loggerConfig.sampleRate = 100;
[[FTSDKAgent sharedInstance] startLoggerWithConfigOptions:loggerConfig];

主进程可通过 client.capabilities.log 确认 Native 是否支持接收页面日志；仅在启用该能力的页面中初始化 Browser Logs。若通过业务 Preload 向页面传递此状态，只暴露所需布尔值，不传递完整 Native 配置。

enableWebViewLog 用于接收页面日志；需要将日志关联到原生 RUM 会话时，同时设置 enableLinkRumData: YES 并按混合模式示例开启 RUM 的 enableTraceWebView。

两种模式都在页面中按以下方式初始化 Browser Logs：

import { datafluxLogs } from '@cloudcare/browser-logs'

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

日志采样统一通过 Native Logger 配置控制。示例将 Browser sessionSampleRate 设为 100，避免页面侧再次降低采样率造成双重采样。

开启会话回放¶

先按接入模式开启回放采集：

• 全量模式：在 native.settings 中设置 replayEnabled: true，并按需设置 replaySampleRate 和 replayPrivacy。
• 混合模式：在原生主程序中按混合模式示例配置 Session Replay 的采样率和隐私保护方式。

回放默认关闭。完成 Native 配置后，在页面的 datafluxRum.init() 之后检查 Bridge 能力，仅在返回 records 时开始录制：

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

records 表示 Native 已提供回放能力，不代表当前会话必然命中回放采样。不要仅通过页面调用强制开启 Native 尚未启用的回放。主进程也可通过 client.capabilities.replay 检查该能力。

接入完成后，可以在观测云中查看页面访问、用户操作和对应的回放。混合模式下，可以在同一会话中查看原生应用与 Electron 页面的访问数据；原生界面和 Electron 页面的回放分别展示。

混合模式中的页面快照由 Browser SDK 管理，Native Bridge 不反向触发页面完整快照。不要使用 client.updateWindow(..., { visible: false }) 作为混合模式暂停录制的方式。全量模式仍保留 Native 与页面的快照同步机制。

打包资源¶

全量模式¶

managed 模式必须先安装 Native 运行时，再将完整目录复制到 ASAR 外。macOS Universal 产物包含 arm64 和 x86_64。使用 npm 自动安装的运行时时，electron-builder 可通过以下 extraResources 配置复制运行时，并把 .node 加入 macOS 二进制签名配置：

{
  "extraResources": [
    {
      "from": "node_modules/@cloudcare/electron-native-adapter/.cloudcare/native/darwin/runtime",
      "to": "native"
    }
  ],
  "mac": {
    "binaries": [
      "Contents/Resources/native/guance_electron.node"
    ]
  }
}

如果使用显式 CLI 安装，将上述 from 改为应用项目的 .cloudcare/native/darwin/runtime。不要只复制 .node 文件，运行时中的资源 Bundle 也必须一起交付。打包后的 Adapter 默认优先使用 process.resourcesPath 下的 native 目录；如果显式配置了 native.directory，打包后也应将其指向该目录，不能继续使用开发机路径。

沿用应用现有的 macOS 签名和公证流程，并将 guance_electron.node 一起签名。发布前需运行打包后的应用，验证 SDK 能正常加载和上报数据。

混合模式¶

混合模式按原生主程序现有流程打包和签名 Native SDK、GuanceElectronWebView 及按需使用的 Session Replay 组件。Electron 按常规方式打包即可。

集成边界¶

• 页面 RUM 事件和日志经 Preload、Main Process 转交 Native SDK；不要自行注册或转发 SDK 内部 IPC Channel。
• Adapter 只接受已登记窗口的主 Frame 事件，子 Frame 不作为独立可信入口。
• traceEnabled 配置的是 Native SDK Trace，不会自动为 Renderer 的 fetch / XHR 配置链路追踪。页面请求需要链路关联时，在 Browser RUM 中另行设置 allowedTracingUrls 和匹配后端的 traceType；可参考仓库 Electron 示例。
• 当前 macOS Adapter 未提供 Windows 接入中的自动 launch_cold、launch_hot Action 上报，不要依赖 enableAppLaunch 在 macOS 上产生这些事件。
• Renderer JavaScript Error 和 Long Task 由 Browser RUM 采集。Electron 的 unresponsive、render-process-gone 不由 Bridge 自动转换为 RUM 错误；原生主程序的崩溃监测也不能替代 Electron 子进程的崩溃采集，需要按应用需求单独接入。
• 限制远程页面的导航、弹窗、权限和允许域名。上传地址和凭据配置在 Electron 主进程或原生主程序中，不写入页面代码。

验证集成¶

1. 启动应用，确认主进程和页面控制台没有 SDK 初始化错误；在 Renderer DevTools Network 中确认没有 RUM 或 Log 直传请求。
2. 访问页面、点击控件、发送请求并触发一条错误和 Long Task，在观测云中确认能查看到对应数据，且应用 ID 使用 Native 配置；开启页面日志后，再发送一条日志验证。
3. 回放关闭时确认 getCapabilities() 不包含 records；开启并命中采样后查看录制结果，确认文本和输入内容符合所选隐私设置。
4. 创建第二个窗口，确认能采集该窗口；使用指定窗口采集时，确认未接入的窗口没有数据。
5. 混合模式下，在同一会话中查看原生应用和 Electron 页面的访问记录。
6. 退出全量模式应用，确认 client.stop() 完成；退出混合模式 Electron 子进程，确认原生 SDK 继续采集和上传。运行打包后的应用，再次验证数据和回放是否正常。

完整示例见 macOS SDK 仓库的 Electron 全量模式示例和原生宿主混合模式示例。

常见问题¶