Electron Configuration and Lifecycle¶

This document is a shared configuration guide for the Windows and macOS Native Bridge. For first-time integration, use the managed Quick Start; for mode selection, see Application Access. Platform host initialization, runtime installation, and packaging remain described separately in Windows and macOS.

Main Configuration¶

In managed mode, configure the application and upload parameters in native.settings of bootstrap(). In external mode, the native host configures the Native SDK; do not pass native.settings.

Windows can retain decimal precision such as 0.1; the default macOS Native Runtime uses integer percentages. If an enabled collection feature passes a decimal using the new fields, the Adapter reports an error instead of rounding. Decimal sampling support for a custom macOS Runtime depends on its actual capabilities; regular sampling and Replay are checked separately. The legacy sampling fields have been deprecated since Adapter 0.1.0-alpha.4 and remain compatible with the original units and existing macOS rounding behavior. When both old and new fields are set in the same configuration, the new fields take precedence, including an explicit value of 0.

The application version actually reported on macOS is determined by the app packaging information. traceEnabled only configures Native Trace; it does not automatically inject Trace Headers into Renderer requests.

User binding and global attributes are managed uniformly through Native SDK capabilities; see Windows Custom Tags and Apple SDK Custom Tags. The Adapter Client does not provide a public user-binding interface equivalent to Browser setUser(); do not modify Native state by referencing internal Adapter modules.

Preload¶

Use only the public entry points of the npm package: the Main process uses @cloudcare/electron-native-adapter; if there is no business Preload, use preload/standalone from the Quick Start; if a Preload already exists, call the installation function once:

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

installElectronRumPreload();

Keep contextIsolation: true, nodeIntegration: false, and sandbox: true. A sandboxed Preload cannot load npm packages directly with a normal Node.js require(); use your application's bundler to bundle the above code and its dependencies, keeping electron as an external dependency. For example, a project that already has esbuild installed can run:

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

Point webPreferences.preload to the absolute path of the output. The standalone Preload already works directly in the sandbox; there is no need to install the bridge again. Do not copy Adapter source code or directly reference non-public files under internal/, core/, or platform/.

Window Management¶

Every window that requires data collection must load Preload and be registered before the page is loaded. autoAttach defaults to false; setting it to true registers existing and subsequently created windows. This is suitable for apps where all windows are trusted and require data collection, but it does not replace Preload.

When monitoring only specific windows, keep autoAttach: false in bootstrap() and register that window:

// client is the return value of bootstrap(); window is a BrowserWindow configured with Preload.
const detach = client.attachWindow(window);
await window.loadFile("index.html");
// Call detach() or client.detachWindow(window) if you need to stop collection early.

Register each window separately; refresh and navigation do not require re-registration. When a window is destroyed, the Adapter automatically removes its registration. For apps that contain untrusted pages, load Preload only for target windows and restrict navigation, pop-ups, permissions, and allowed domains for remote pages.

Renderer¶

managed and external modes share the Renderer initialization in Quick Start. Each page initializes Browser RUM after the Bridge is ready; the actual application ID, Session, sampling, and upload remain managed by the Native SDK. The existence of the Bridge does not guarantee that data was delivered; you also need to check Main transport errors and server-side reception results.

Browser Logs¶

First enable the Native logging capability: for managed mode, set loggingEnabled: true; for external mode, configure it as described in Windows Host or macOS Logger. The main process checks the actual capability through client.capabilities.log and initializes Browser Logs only on pages where this capability is enabled; if you pass this state through a business Preload, expose only a boolean value.

After installing @cloudcare/browser-logs (Bridge integration requires 3.3.6 or higher), use it in a Renderer that has completed RUM Bridge integration:

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

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

Keep the Browser sample rate at 100%; the actual log sampling is controlled by Native. When the Native logging capability is disabled, do not initialize Logs independently on the page as a fallback upload path.

Session Replay¶

Replay is disabled by default. The Native SDK configuration, the corresponding component, and the Bridge's actual capability requirements must all be satisfied. First complete the Windows Optional Replay Runtime or the macOS Replay Configuration, then check the capability after datafluxRum.init():

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

records indicates that Native provides replay capability; it does not mean the current Session is necessarily sampled. Do not force Replay on by copying the Browser standalone recording flow. The main process can also check client.capabilities.replay; verification for missing components, disabled state, and post-enable state is performed according to the platform documentation.

Lifecycle and Diagnostics¶

bootstrap() returns a Client that provides capabilities, attachWindow(), detachWindow(), updateWindow(), transportState, and an idempotent stop(). Use onError to receive asynchronous transport and window handling errors, and use transportState to check writable status, backpressure, and transport failures.

On normal exit, you must wait for stop(); see the Quick Start Main example for complete asynchronous exit handling. Stopping collection is not confirmation that all offline data has been uploaded. For parameters such as Windows connection timeout, Bridge output, and startup Action, see Platform Configuration. macOS does not provide the Windows automatic startup Action; see macOS Replay for the visibility boundaries of the replay window in mixed mode.