Electron Application Integration Guide¶
Back to Electron Application Integration
Native SDK Integrators Should Use the Native Bridge
This page describes the integration approach in which Browser RUM independently manages the Session and uploads directly. If you need the Windows or macOS Native SDK to manage Session, sampling, context, persistence, and uploads, first read Choosing an Electron Integration Approach. If your application is primarily built on Electron, use the managed Quick Start. The Native Bridge mode cannot directly reuse the actual applicationId, clientToken, site, or sessionPersistence configuration on this page.
An Electron application consists of a main process and renderer processes. Because the RUM SDK runs in a browser environment, it should only be initialized in the renderer process to collect page views, resources, requests, errors, and user action data from the windows.
This document explains how to integrate Electron applications based on the current SDK initialization parameters.
Integration Principles¶
- Initialize the RUM SDK only in the renderer process. Do not initialize it in the main process.
- Each renderer page associated with a monitored
BrowserWindow,BrowserView, orwebviewmust be integrated once. - If pages are loaded via
file://, you must usesessionPersistence: 'local-storage'to avoid relying on unavailable or unstable cookies. - If pages are loaded via
https://, you can continue using the default cookie-based session strategy, or uselocal-storageconsistently, but make sure the session strategy stays consistent between RUM and the Logs SDK. - If the same Electron application uses both local
file://pages and remotehttp(s)://pages, they are isolated by the browser's same-origin policy and usually generate different sessions.
Recommended Integration Methods¶
NPM Integration¶
For Electron applications that use Webpack, Vite, Rollup, or similar tools to build renderer code.
Initialize in the renderer entry file:
import { datafluxRum } from '@truewatchtech/browser-rum'
datafluxRum.init({
applicationId: '<Application ID>',
// Using Public DataWay ingestion
clientToken: '<clientToken>',
site: '<Public DataWay Address>',
// If using DataKit ingestion, configure datakitOrigin instead
// datakitOrigin: '<DataKit domain or IP>',
service: 'electron-renderer',
env: 'production',
version: '<Application Version>',
sessionSampleRate: 100,
trackUserInteractions: true,
// Required for file:// pages
sessionPersistence: 'local-storage'
})
If you need Session Replay:
CDN Integration¶
For applications that maintain renderer HTML directly. It is recommended to bundle the SDK files as part of the application's static assets to avoid relying on a remote CDN in offline or poor network conditions.
<script src="./vendor/dataflux-rum.js" type="text/javascript"></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: '<Application ID>',
clientToken: '<clientToken>',
site: '<Public DataWay Address>',
service: 'electron-renderer',
env: 'production',
version: window.__APP_VERSION__,
sessionSampleRate: 100,
trackUserInteractions: true,
sessionPersistence: 'local-storage'
})
</script>
If the renderer page is always loaded via https:// and cookies are available, you can omit sessionPersistence.
Main Process Example¶
The main process is responsible for creating windows. It does not need to import or initialize the RUM SDK. It is recommended to pass only necessary information such as version and channel to the renderer.
const { app, BrowserWindow } = require('electron')
const path = require('path')
function createWindow() {
const win = new BrowserWindow({
width: 1200,
height: 800,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false
}
})
win.loadFile('index.html')
}
app.whenReady().then(createWindow)
preload.js only needs to expose safe, read-only application information:
const { contextBridge } = require('electron')
const { version } = require('./package.json')
contextBridge.exposeInMainWorld('electronAppInfo', {
version
})
Then read this information in the renderer and use it in the RUM configuration:
datafluxRum.init({
applicationId: '<Application ID>',
clientToken: '<clientToken>',
site: '<Public DataWay Address>',
service: 'desktop-app',
env: 'production',
version: window.electronAppInfo.version,
sessionSampleRate: 100,
trackUserInteractions: true,
sessionPersistence: 'local-storage'
})
Multi-window Integration¶
If the application opens multiple windows at the same time:
- The renderer page in each window must initialize the RUM SDK.
- When using
sessionPersistence: 'local-storage', localStorage synchronization between windows may have a very short delay. - If many windows are created simultaneously immediately after initialization, short-lived temporary sessions may appear. It is recommended to leave at least tens of milliseconds between window creation and initialization, or create windows one by one in business order.
Local and Remote Pages¶
Electron applications commonly have the following page sources:
| Page Source | Recommended Configuration | Description |
|---|---|---|
file:// local pages |
sessionPersistence: 'local-storage' |
Cookies are unreliable; you must use localStorage to store the session. |
https:// remote pages |
Default cookies or local-storage |
If using default cookies, ensure the page domain and security policy allow writing cookies. |
Mixed file:// and https:// |
Integrate and analyze separately | Due to the same-origin policy, local and remote pages usually do not share the same session. |
If the application navigates from a local landing page to a remote site, expect them to appear as two different sessions in RUM. It is recommended to correlate them during analysis using consistent user.id, service, env, and version fields.
API Requests and Distributed Tracing¶
fetch and XMLHttpRequest in the renderer are collected automatically using the browser SDK logic. To inject trace headers into backend API requests, configure allowedTracingUrls:
When integrating via NPM + TypeScript, use the TraceType enum imported from the browser-core package for traceType:
import { TraceType } from '@truewatchtech/browser-core'
import { datafluxRum } from '@truewatchtech/browser-rum'
datafluxRum.init({
applicationId: '<Application ID>',
clientToken: '<clientToken>',
site: '<Public DataWay Address>',
service: 'desktop-app',
env: 'production',
version: window.electronAppInfo.version,
sessionPersistence: 'local-storage',
allowedTracingUrls: [
'https://api.example.com',
/https:\/\/.*\.internal-api\.example\.com/
],
traceType: TraceType.DDTRACE
})
The CDN integration has no module imports. When explicitly specifying the type, use the runtime value 'ddtrace'; this is also the default value when it is not configured.
Do not add file:// page addresses to allowedTracingUrls. This configuration is used to match backend API requests, not the renderer page itself.
Errors and Source Maps¶
Error stack traces from Electron local pages often begin with file://, so the server may not be able to match Source Maps as directly as it can for public URLs. It is recommended to:
- Keep
service,env,version, and build artifact versions consistent. - Generate Source Maps for renderer build output and save them by release version.
- If you need to rewrite local file paths, add business context in
beforeSendfor easier retrieval later.
datafluxRum.init({
// ...
beforeSend: (event) => {
if (event.type === 'error') {
event.context = {
...event.context,
electron: true,
rendererUrl: window.location.href
}
}
return true
}
})
CSP and Workers¶
If Session Replay, compressIntakeRequests, or canvas recording is enabled, the SDK may use Workers. If your Electron application applies a strict CSP, you need to allow the corresponding Worker sources.
The default inline Worker usually requires:
If blob: is not allowed, bundle the Worker files as application static assets and configure same-origin URLs:
If you use @truewatchtech/browser-rum-slim, this package does not include Session Replay or compressIntakeRequests compression, so you generally do not need to configure Workers for these two features.
Security Recommendations¶
- Do not expose RUM tokens or any write APIs for other sensitive configuration in the main process.
preloadshould only expose necessary read-only information, such as application version, channel, and build number.- Keep
contextIsolation: trueandnodeIntegration: false. - Do not report absolute local file paths, user home directories, or other sensitive information in
beforeSend. - Sanitize fields such as user input, file names, and paths before writing them to custom context.
Verification¶
After integration, verify in the following order:
- Open the target window of the Electron application.
- Confirm RUM reporting requests in the DevTools Network panel.
- Trigger a page visit, button click, API request, and front-end error.
- Confirm that
view,action,resource, anderrordata arrives in TrueWatch. - Check whether the session for the same user matches expectations across multiple windows or when switching between local and remote pages.
For local debugging, you can temporarily add beforeSend to print event types:
datafluxRum.init({
// ...
beforeSend: (event) => {
console.log('[RUM]', event.type, event)
return true
}
})
FAQ¶
Why is there no data from the main process?¶
The RUM SDK is a browser-side SDK and only collects page behavior in the renderer process. Crashes, IPC, file system, or native module errors in the main process must be handled by the application's own logging or crash collection solution.
Why does the file:// page have no session?¶
Usually this is because sessionPersistence: 'local-storage' is not configured, or localStorage is disabled in the renderer page environment. First check this configuration and whether localStorage is available.
Why does the session change after navigating from a local page to a remote page?¶
file:// and https:// are different origins, so the browser does not share the same cookies or localStorage. It is recommended to use setUser() to set a stable user ID and correlate by user during analysis.
Why do very short sessions appear in multiple windows?¶
When multiple windows are initialized at the same time, localStorage synchronization between windows may have a very short delay. It is recommended not to create and initialize many windows at the exact same moment; leave a brief interval between window creations.