Skip to content

Electron Monitoring

This page covers the Windows native host, runtime, Replay, and packaging instructions. For first-time integration, choose a solution from Electron App Integration; if the application itself is Electron, first complete the managed Quick Start.

The Windows SDK integrates with Electron through Native Bridge: Browser RUM and Browser Logs in the Renderer collect page data, and the Electron Main Process passes the data to the Windows Native Core, which centrally manages the application ID, Session, sampling, global context, persistent queue, and uploads.

Select a mode based on who initializes the Native SDK:

Mode Use Cases Native Runtime Source SDK Owner
Mixed Mode (external) C++ desktop applications embedding Electron pages Provided by the host, e.g., the vcpkg base package C++ host
Managed Mode (managed) The application itself is Electron Downloaded during npm installation; an explicit directory is also supported Bridge EXE managed by the Adapter

The two modes cannot be used simultaneously. The page side shares the same Preload, attachWindow(), and Renderer initialization approach.

This approach differs from Electron standalone integration for Web RUM. In the Windows SDK integration, the Renderer does not upload data directly, nor does it configure the real application ID, reporting endpoint, or Client Token.

The data flow is as follows:

Electron Renderer
  @cloudcare/browser-rum / @cloudcare/browser-logs collectors
          |
          | FTWebViewJavascriptBridge.sendEvent(JSON)
          v
Secure Preload -> allowlisted IPC -> Electron Main Process
          |
          v
Windows Native Core (initialized by C++ host or Bridge EXE)
  Native RUM / Log / Session / Sampling / Context / Persistence / Upload

Integrate Electron

Install Dependencies

Electron Native Adapter Version

When the application itself is Electron, install dependencies and integrate Main, Preload, and Renderer following the Common Quick Start. See Supported Environments for Electron version requirements.

npm installation and the runtime installer require Node.js 18+; users of the packaged application do not need to install Node.js separately. Windows supports x64, x86 (ia32 in Electron/Node.js), and arm64, and requires the Microsoft Visual C++ v14 Redistributable and Windows Universal CRT that match the runtime architecture.

The published npm package does not bundle Native binaries, but postinstall downloads and verifies the Native Runtime by platform and architecture without local compilation. Managed mode locates this runtime automatically by default and does not require vcpkg to be installed first. The Adapter also supports macOS; this page describes Windows Native Bridge integration.

Important Version Notes

Adapter 0.1.0-alpha.3 adds Windows x86/arm64 runtime selection, verification, and packaging support, and pins the default Native Runtime to Windows SDK vcpkg_0.1.0-alpha.8 and macOS SDK 1.6.8-alpha.6. These are the default dependencies of this version and do not mean that later versions always use the same Native SDKs.

The Adapter, Windows SDK, and macOS SDK each maintain their own versions. The actual defaults are determined by the package.json.nativeRuntime field of the installed npm package.

Integrating Windows Replay as a separate package requires Adapter 0.1.0-alpha.5 and Windows SDK vcpkg_0.1.0-alpha.10 or later; alpha.5 uses this Windows SDK by default. The base runtime does not include Replay by default; you must explicitly install the supplemental component of the same version and architecture.

When using only mixed mode, you can set the PowerShell environment variable $env:GUANCE_NATIVE_SKIP_DOWNLOAD = "1" before installation to skip the download of the unused runtime; clear this variable before switching back to managed mode installation.

Initialize Native Bridge

Managed Mode

The Electron Main Process starts and manages the Bridge EXE. See managed Quick Start for a complete initialization and shutdown example. See Main Configuration for the common native.settings fields, sampling units, and version differences.

If you need a custom cache directory on Windows, set cachePath to path.join(app.getPath("userData"), "native-rum-cache"), where path is the node:path module and app is the Electron App.

Other optional configuration:

Location Parameter Description
native.settings traceType Default w3c_traceparent
native.settings traceAllowedUrls Native Trace URL rule string
native.settings httpTimeoutMs Upload timeout, default 10000 ms, range 1..300000
native (managed) readyTimeoutMs, stopTimeoutMs Startup handshake and shutdown wait time, default 10000 and 3000 ms
native (managed) onNativeOutput Receives (stream, text) for diagnosing Bridge stdout and stderr
native (external) timeoutMs, retryDelayMs Connection timeout and retry interval, default 10000 and 100 ms
bootstrap() enableAppLaunch Default true; automatically collects cold launch and hot launch Actions
native mode managed for Managed Mode, external for Mixed Mode
native (managed) directory Custom Native Runtime directory; auto-located when omitted
bootstrap() onError Receives async transmission and window handling errors

For shutdown cleanup and the common Client API, see Lifecycle and Diagnostics. startFullMode() and connectMixedMode() are kept only for compatibility with earlier versions; new integrations should use bootstrap() uniformly.

The Adapter enables enableAppLaunch by default, which automatically generates launch_cold and launch_hot Actions based on the Electron application lifecycle, the first frame of trusted windows, and Browser View context; set it to false if automatic launch Actions are not needed. To associate cold launches with the first Browser View, start or connect the Bridge as early as possible and call attachWindow() immediately after creating the window.

Mixed Mode

The C++ host initializes the Windows SDK first, then binds the Bridge Server to the existing 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; // Supported since 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);

// On application exit, stop the Bridge Server first, then shut down the SDK.
guance_electron_bridge_server_stop(bridge);
guance_sdk_shutdown(sdk);

The Electron Main Process connects to the named pipe of the same name:

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,
});

In mixed mode:

  • Do not start guance_windows_electron_bridge.exe, otherwise a second SDK Handle will be created;
  • Electron no longer passes the application ID, DataKit/Dataway, cache, or upload configuration;
  • The C++ host must ensure that the SDK Handle outlives the Bridge Server;
  • When collecting Browser Logs, you also need to enable Native custom logging and set logging_enabled to 1.

Integrate Preload and Windows

Install the bridge following Common Preload Configuration, then register windows before loading pages following Window Management; managed and external modes share this flow.

Initialize Renderer

Initialize page RUM, optional logs, and Replay following Common Renderer Integration. The real application ID, upload endpoint, and credentials are managed by Native.

Session Replay is experimental and disabled by default

getCapabilities() returns records only when both the Native SDK and Bridge configuration have Replay enabled, and the matching Replay component is actually available. The Renderer must decide whether to start recording based on this capability; it cannot force-enable Replay on its own. In managed mode, set replayEnabled: true in native.settings; in mixed mode, the host configures the Native SDK and Bridge Server and manages the recording lifecycle.

Install Optional Replay Runtime

In managed mode, install the Replay supplemental package during development or build; the DLL is not downloaded at application runtime. Run the following in the application root directory:

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

Pass the runtime directory output by the CLI to native.directory during development, and to nativeDirectory of stageWindowsRuntime() during packaging; after packaging, use resources/native for automatic location. For x86 and arm64, select win32-x86 and win32-arm64 respectively. You can also set $env:GUANCE_NATIVE_INSTALL_REPLAY = "1" before npm installation so that postinstall installs the supplemental component into the npm package's runtime directory, after which it is located and packaged using the default approach.

For offline installation, prepare both the base archive and the Replay archive, along with their respective .sha256 files:

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

The installer verifies the SDK version, architecture, and file hashes in both manifests, and places guance_windows_replay.dll in the same directory as the base DLL. After installation, you still need to set replayEnabled: true. If Replay is missing or fails to load, regular RUM continues to work, and the Renderer does not gain the records capability.

In mixed mode, the component is provided by the C++ host through the vcpkg replay feature, and the DLL is in the same directory as the host's base SDK; the Electron Adapter decides whether to forward Replay based on the actual capabilities in the Bridge Server handshake. See Optional Component Installation for details.

Package Resources

In managed mode, call the public packaging helper function before signing the application to copy the complete runtime outside the ASAR:

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

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

By default, the helper function locates the runtime installed in the npm package and copies it to resources/native; the target directory must be empty. After packaging, managed mode automatically locates this directory without setting native.directory. Native EXE, DLL, and manifest resources must be kept intact and must not be placed inside app.asar.

When Replay is installed, stageWindowsRuntime() also verifies and copies the supplemental DLL and replay-manifest.json. The base runtime and the Replay supplemental component must have the same version and architecture.

For cross-architecture packaging, install the target runtime first, then explicitly pass the target arch. Windows supports x64, x86 / ia32, and arm64. Runtimes installed via the CLI must be specified through the nativeDirectory parameter of the helper function.

When manually using the vcpkg tools directory, you can continue to copy via electron-builder's extraResources and specify the resource location using sdkDirectory in the vcpkg section below:

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

Managed mode must deliver the guance_windows_electron_bridge.exe and the adjacent guance_windows_native.dll of the same SDK version, and the application packaging tool must also include @cloudcare/electron-native-adapter. Mixed mode does not require copying the vcpkg tools directory; the Native DLL is still delivered by the C++ host's existing deployment flow, and the JavaScript Adapter is still provided by the npm dependency. Do not rely on the current working directory or absolute paths from the development machine to locate resources.

Optional: Provide Native Runtime via vcpkg

If the host owns the Native SDK, or you need to build the runtime yourself, configure the SDK vcpkg registry following Quick Start. The JavaScript Adapter is still installed separately via npm. When providing the runtime manually in managed mode, enable electron-bridge:

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

In mixed mode, install the base Native package; when using Replay, add "features": ["replay"] to that dependency. You do not need to enable the old electron-bridge feature:

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

Run the following in the directory containing vcpkg.json:

vcpkg install --triplet x64-windows

The vcpkg command above uses x64 as an example. When manually using the vcpkg tools directory, pass sdkDirectory below to native.directory; the default npm download flow does not require this configuration:

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",
    );

Adjust the relative hierarchy in the development directory according to your application structure; do not rely on the current working directory or hardcode absolute paths from the development machine.

Custom and Offline Runtime Installation

If you used --ignore-scripts during npm installation, or need a different target architecture, run the following in the application root directory:

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

Windows targets are win32-x64, win32-x86, and win32-arm64; macOS is darwin-universal. <sdk-tag> uses the complete tag of the Native SDK Release, retaining existing prefixes such as vcpkg_, nuget_, or v; the corresponding runtime assets must exist under the tag.

Offline installation requires the SDK .tar.gz and the adjacent .tar.gz.sha256 checksum file:

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

The CLI installs the runtime into the application root directory. During development, pass the output directory to native.directory; during packaging, pass it to nativeDirectory of stageWindowsRuntime(); after packaging, remove the development directory configuration and use the auto-located resources/native.

npm postinstall supports the following environment variables (set them in PowerShell with $env:VariableName = "value"):

Environment Variable Purpose
GUANCE_NATIVE_RUNTIME_ARCHIVE Use a local SDK archive and its adjacent checksum file instead of downloading
GUANCE_NATIVE_INSTALL_REPLAY Set to 1 to explicitly install the Replay supplemental component during Windows postinstall
GUANCE_NATIVE_REPLAY_ARCHIVE Use a local Replay archive and its adjacent checksum file; using it via the CLI implicitly enables Replay installation
GUANCE_NATIVE_REPLAY_ASSET_NAME Override the download filename of the Replay supplemental archive
GUANCE_NATIVE_RUNTIME_TARGET Specify the target platform and architecture
GUANCE_NATIVE_SDK_VERSION Override the Native SDK tag pinned in the package
GUANCE_NATIVE_RUNTIME_ASSET_NAME Override the download asset filename
GUANCE_NATIVE_RUNTIME_DOWNLOAD_BASE_URL Use an HTTPS mirror with the directory structure /<sdk-tag>/<filename>
GUANCE_NATIVE_SKIP_DOWNLOAD Set to 1 to skip runtime installation; suitable for external mode

The archive must match the specified SDK version and architecture. Providing an offline Native Runtime only does not mean npm is fully offline; you also need to prepare the npm packages and their dependency cache in advance. Private source checkouts skip the automatic download; when debugging with local file: dependencies, you need to prepare the runtime yourself.

Integration Boundaries

  • The Main Process uses only the public interfaces exported by @cloudcare/electron-native-adapter and must not register SDK-internal IPC Channels itself;
  • Do not expose the application ID, Client Token, DataKit/Dataway address, native Session, or complete Native configuration to the Renderer;
  • The Main Process registers only trusted webContents. For remote pages, you also need to restrict navigation, pop-ups, permissions, and allowed domains;
  • Managed mode configures Native Trace through native.settings; mixed mode is configured by the host. The Adapter does not inject Trace configuration into the Renderer, nor does it automatically add Trace Headers to page requests as a result;
  • Renderer JavaScript Errors and Long Tasks are collected by Browser RUM; unresponsive, render-process-gone, and Main Process Crashes are not automatically reported by the Bridge. If needed, integrate Electron crashReporter or another Crashpad service separately.

Verify Integration

  1. In the Renderer DevTools Network tab, confirm that there are no direct RUM or Log upload requests;
  2. Trigger a View, Action, Resource, Error, Long Task, and a Browser Log, and confirm the data in the console;
  3. Confirm that the data uses the application ID, Session ID, and sdk_name=df_windows_rum_sdk configured in Native;
  4. Confirm that the Browser Log warn status appears as warning in Native Logs and that custom attributes are preserved;
  5. When Replay is disabled or the component is missing, confirm that getCapabilities() does not include records; after the component is installed and enabled, confirm that recording data is reported normally;
  6. In mixed mode, after closing the Electron pages, confirm that the C++ SDK is still running; in managed mode, after exiting the application, confirm that the Bridge EXE shuts down properly.

For acceptance, refer to the Electron Native Adapter Consumer Acceptance and Electron Sample in the Windows SDK repository. For local debugging, you can use npm file: dependencies; production applications should use the published package and manage the actually installed version through the application's lockfile.

Feedback

Is this page helpful?