|
| 1 | +--- |
| 2 | +title: "Electron SDK compatibility" |
| 3 | +description: "Review supported Electron versions, operating systems, bundlers, module formats, and current limits for the Electron RUM SDK" |
| 4 | +keywords: ["RUM", "Electron SDK", "compatibility", "bundlers", "known limits"] |
| 5 | +--- |
| 6 | + |
| 7 | +This page describes the Electron SDK support scope and current limits so you can confirm whether your project meets the requirements before integration. |
| 8 | + |
| 9 | +## Support scope |
| 10 | + |
| 11 | +| Item | Support | |
| 12 | +|------|---------| |
| 13 | +| Electron version | 39 and later (`peerDependencies: electron >= 39`) | |
| 14 | +| Operating systems | macOS, Windows, Linux | |
| 15 | +| Main-process package | `@flashcatcloud/electron-sdk` | |
| 16 | +| Renderer package | `@flashcatcloud/browser-rum` (the same package as the Web SDK) | |
| 17 | +| Module formats | Both CommonJS and ESM builds are shipped | |
| 18 | +| RUM data source | Main-process events carry `source: "electron"`; renderer events keep `source: "browser"` with `container.source: "electron"` | |
| 19 | +| Reporting | `POST https://<site>/api/v2/rum` | |
| 20 | + |
| 21 | +## Bundlers |
| 22 | + |
| 23 | +| Tool | Support | Notes | |
| 24 | +|------|---------|-------| |
| 25 | +| Vite / electron-vite / Forge + Vite | Plugin provided | `@flashcatcloud/electron-sdk/vite-plugin` | |
| 26 | +| Webpack / Forge + Webpack | Plugin provided | `@flashcatcloud/electron-sdk/webpack-plugin` | |
| 27 | +| esbuild | Plugin provided | `@flashcatcloud/electron-sdk/esbuild-plugin` | |
| 28 | +| No main-process bundling (running `.js` directly) | Supported | Write `import '@flashcatcloud/electron-sdk/instrument'` as the first import | |
| 29 | +| Other bundlers | No plugin | You must guarantee the instrument entry point runs before `require('electron')` and keep `dd-trace` and the SDK external | |
| 30 | + |
| 31 | +<Warning> |
| 32 | +When the main process is bundled, the matching plugin is **required**. It preserves the instrument entry order, keeps `dd-trace` and the SDK as runtime dependencies, and copies the SDK's own preload into the packaged output; missing any of these steps can break main-process network tracing or the renderer bridge. The Electron SDK registers its preload per `session`; this does not depend on `dd-trace` wrapping `BrowserWindow`. |
| 33 | +</Warning> |
| 34 | + |
| 35 | +## Renderer page loading |
| 36 | + |
| 37 | +A window's own host is always on the bridge allowlist, so **every loading method works out of the box** with no configuration. |
| 38 | + |
| 39 | +| Loading method | Bridge available | Notes | |
| 40 | +|----------------|------------------|-------| |
| 41 | +| `loadURL('http://localhost:<port>')` | Yes | No configuration needed | |
| 42 | +| `loadURL('https://<host>')` | Yes | No configuration needed | |
| 43 | +| Custom protocol (`protocol.handle()` + `loadURL('app://…')`) | Yes | No configuration needed | |
| 44 | +| `loadFile()` (`file://`) | Yes | `location.hostname` is an empty string, the allowlist becomes `[""]`, and it still self-matches | |
| 45 | +| Third-party pages in `<webview>` / `BrowserView` | Needs configuration | Add the other host to `allowedWebViewHosts`; matching supports subdomain suffixes | |
| 46 | + |
| 47 | +## Automatic collection |
| 48 | + |
| 49 | +| Capability | Support | Notes | |
| 50 | +|------------|---------|-------| |
| 51 | +| Main-process session | Supported | Persisted at `userData/_dd_s`, reused after restart | |
| 52 | +| Main-process view | Supported | One view per main-process instance | |
| 53 | +| Node uncaught exceptions / promise rejections | Supported | `process.on('uncaughtException' \| 'unhandledRejection')` | |
| 54 | +| Main-process HTTP requests | Supported | Traced by `dd-trace` for `http`/`https`, `fetch`, and `net.fetch`, converted to `resource` | |
| 55 | +| Signed-in user identity | Supported | The main process exposes `setUser` / `getUser` / `clearUser` and attaches identity to main-process and bridged renderer events | |
| 56 | +| Native crash capture | Supported | Electron `crashReporter` writes minidumps, parsed and uploaded on the next startup | |
| 57 | +| Renderer / child process terminations | Supported | Listens for `render-process-gone` / `child-process-gone`, covering terminations that produce no dump | |
| 58 | +| Native crash symbolication | Supported | Requires uploading Breakpad symbol files, see [Upload native crash symbols](/en/rum/sdk/electron/advanced-config#upload-native-crash-symbols) | |
| 59 | +| Renderer view / action / resource / error / Web Vitals | Supported | Collected by `@flashcatcloud/browser-rum` | |
| 60 | +| Error stack path normalization | Supported | Stacks from both processes are rewritten to `app:///<path relative to the app root>`, so source maps need not be uploaded against installation paths; disable with `normalizeStackPaths: false` | |
| 61 | +| FCP / LCP correction for pre-warmed windows | Supported | Paint metrics of a `BrowserWindow` created hidden are rebased onto its first visible moment; disable with `correctPrewarmedViewTimings: false` | |
| 62 | +| Session Replay | Supported | Recorded and uploaded directly by the renderer; requires `sessionReplayDirectUpload` and a CSP that allows it, see [Session Replay](/en/rum/sdk/electron/sdk-integration#session-replay) | |
| 63 | + |
| 64 | +## Current limits |
| 65 | + |
| 66 | +| Limit | Description | |
| 67 | +|-------|-------------| |
| 68 | +| Native crash symbolication needs symbols uploaded | Native crash frames match Breakpad symbol files on the module id. Without an upload they stay as **raw addresses**, and **nothing reports an error or a warning**. Re-upload on every Electron upgrade, and for every platform and architecture you ship — see [Upload native crash symbols](/en/rum/sdk/electron/advanced-config#upload-native-crash-symbols) | |
| 69 | +| Code outside the app root is not normalized | Stack path normalization is anchored on `app.getAppPath()`, so native modules under `app.asar.unpacked` and scripts loaded from outside the application root are reported as they are. Source maps for those files have to be aligned with their real paths | |
| 70 | +| `source` on renderer events | Even with the bridge working, renderer events keep `source: browser` and are attributed through `container.source: electron`. Filter a whole application with `source:electron OR container.source:electron` | |
| 71 | +| Session Replay depends on a permissive CSP | Recording creates a blob Worker in the renderer and connects straight to the intake. If the page CSP does not allow `worker-src blob:` and the intake origin, replay fails **completely silently**: `session.has_replay` stays `0`, no segment arrives, and the only trace is one line in the renderer console. See [CSP requirements for Session Replay](/en/rum/sdk/electron/sdk-integration#csp-requirements-for-session-replay) | |
| 72 | +| Replay segments are dropped when the intake is unreachable | Replay segments are uploaded directly by the renderer and do not use the main process's disk-backed retry. A genuine outage (`navigator.onLine === false`) queues segments in an in-memory retry queue and resends them on recovery; but when the machine is online and the intake is not reachable — a blocked request, a down intake, a DNS or proxy failure — segments are dropped immediately and never resent, and the first segment afterwards carries no full snapshot, so that stretch of the replay renders garbled. The retry queue is not written to disk and does not survive process exit. Main-process events are unaffected. See [Replay segments are dropped when the intake is unreachable](/en/rum/sdk/electron/sdk-integration#replay-segments-are-dropped-when-the-intake-is-unreachable) | |
| 73 | +| APM / distributed tracing | Flashduty has no span intake today. IPC and child-process command spans collected by `dd-trace` are dropped locally; only HTTP spans become RUM `resource` events | |
| 74 | +| Log reporting | Log-type events sent over the bridge from renderers are not forwarded to the backend in this version | |
| 75 | +| Main-process Web Vitals | The main process is a Node.js runtime with no DOM or rendering pipeline, so it produces no LCP / INP / CLS, long task, or user action data. The console hides the performance section for main-process views | |
| 76 | +| Main-process RUM has no `env` | `env` is currently written only into the span envelope that is not uploaded; it is not attached to main-process RUM events. Renderer events keep the `env` from `flashcatRum.init()` | |
| 77 | +| No renderer Operation API | The currently required `@flashcatcloud/browser-rum` `0.0.7` does not expose `startOperation` / `succeedOperation` / `failOperation`. Renderer-triggered workflows must call the main-process API through the application's own preload / IPC surface | |
| 78 | +| Session renewal signal | Only renderer `webContents` input events `mouseDown`, `mouseWheel`, `keyDown`, and `rawKeyDown` renew the session. Background activity does not; RUM events after expiry are discarded until the next valid input creates a new session | |
| 79 | +| Upload scheme fixed to HTTPS | The `https://` in the `https://<site>/api/v2/rum` template is hardcoded. If a self-hosted intake serves plain HTTP only, changing `site` does not help — use `proxy`. See [Advanced configuration](/en/rum/sdk/electron/advanced-config#when-a-proxy-is-required) | |
| 80 | +| No stack on termination events | `render-process-gone` / `child-process-gone` events carry no call stack — the main process cannot unwind a process that is already gone | |
| 81 | +| Paint metric correction covers `BrowserWindow` only | `WebContentsView` and `<webview>` have no `show` event, so the SDK cannot observe when they become visible and their paint metrics are reported as they are. In addition, the FCP / LCP of a view whose window was never `show()`n are discarded rather than reported — see [Advanced configuration · FCP and LCP of pre-warmed windows](/en/rum/sdk/electron/advanced-config#fcp-and-lcp-of-pre-warmed-windows) | |
| 82 | +| Main-process view counters | `view.action.count` and its siblings count main-process events only, not events bridged from renderers | |
| 83 | + |
| 84 | +## Symbolication compatibility |
| 85 | + |
| 86 | +| Frame type | Resolution | Files to upload | |
| 87 | +|------------|------------|-----------------| |
| 88 | +| Renderer JavaScript | Source maps restore the original file, function name, and line/column; the SDK normalizes stack paths to `app:///…` by default | `.map` files produced by the build | |
| 89 | +| Main-process JavaScript | Resolved with source maps; the SDK converts main-process stacks into the frame format the backend parses, and normalizes their paths too | `.map` files for the main-process bundle | |
| 90 | +| Native crash frames (C/C++) | Matched against Breakpad symbol files by module id, resolving function name, file and line; resolved when you open the crash, so a later upload still applies | A `.sym` per module, including Electron's official symbol bundle | |
| 91 | + |
| 92 | +See [Advanced configuration · Upload source maps](/en/rum/sdk/electron/advanced-config#upload-source-maps) for the upload procedure. |
| 93 | + |
| 94 | +<Tip> |
| 95 | +The `service` and `version` values used at upload time must exactly match the ones passed to the SDK. Otherwise the console receives error events but cannot map stack frames back to source — and **nothing reports an error**. Note that a renderer event takes its `version` from `flashcatRum.init()` only; the one passed to the main-process `init()` does not apply, see [Advanced configuration · The version must match the renderer process](/en/rum/sdk/electron/advanced-config#the-version-must-match-the-renderer-process). Make source map upload part of your release build. |
| 96 | +</Tip> |
| 97 | + |
| 98 | +## Related pages |
| 99 | + |
| 100 | +<CardGroup cols={3}> |
| 101 | +<Card title="SDK integration" icon="plug" href="/en/rum/sdk/electron/sdk-integration"> |
| 102 | +Integrate both the main process and renderer processes. |
| 103 | +</Card> |
| 104 | + |
| 105 | +<Card title="Advanced configuration" icon="sliders" href="/en/rum/sdk/electron/advanced-config"> |
| 106 | +Configure batching, proxy, manual reporting, and source map upload. |
| 107 | +</Card> |
| 108 | + |
| 109 | +<Card title="Data collection" icon="database" href="/en/rum/sdk/electron/data-collection"> |
| 110 | +See which event types and fields each process contributes. |
| 111 | +</Card> |
| 112 | +</CardGroup> |
0 commit comments