Electron Application Integration Guide¶

An Electron application consists of a main process and renderer processes. The RUM SDK runs in the browser environment, so it should only be initialized in the renderer process to collect data on page views, resources, requests, errors, and user interactions within the window.

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, not in the main process.
• Each renderer page corresponding to a monitored BrowserWindow, BrowserView, or webview needs to be integrated once.
• If pages are loaded via file://, you must use sessionPersistence: 'local-storage' to avoid relying on unavailable or unstable cookies.
• If pages are loaded via https://, you can continue using the default cookie session strategy; you can also uniformly use local-storage, but you need to ensure the session strategy is consistent between the RUM and Logs SDKs.
• If the same Electron application uses both local file:// pages and remote http(s):// pages, they will be isolated by the browser's same-origin policy and typically generate different sessions.

Recommended Integration Methods¶

NPM Integration¶

Suitable for Electron applications that use Webpack, Vite, Rollup, etc., to build renderer code.

npm install @cloudcare/browser-rum

Initialize in the renderer entry file:

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

datafluxRum.init({
  applicationId: '<Application ID>',

  // Public DataWay integration
  clientToken: '<clientToken>',
  site: '<Public DataWay Address>',

  // If using DataKit integration, configure datakitOrigin instead
  // datakitOrigin: '<DataKit Domain or IP>',

  service: 'electron-renderer',
  env: 'production',
  version: '<Application Version>',
  sessionSampleRate: 100,
  trackUserInteractions: true,

  // Required configuration for file:// pages
  sessionPersistence: 'local-storage'
})

If Session Replay is needed:

datafluxRum.startSessionReplayRecording()

CDN Integration¶

Suitable for applications that directly maintain renderer HTML. It is recommended to package the SDK file as part of the application's static resources to avoid reliance on remote CDNs in offline or poor network scenarios for desktop applications.

<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 configuring sessionPersistence.

Main Process Example¶

The main process is responsible for creating windows and does not need to import or initialize the RUM SDK. It is recommended to only pass 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 can expose only safe, read-only application information:

const { contextBridge } = require('electron')
const { version } = require('./package.json')

contextBridge.exposeInMainWorld('electronAppInfo', {
  version
})

Then read and write to the RUM configuration in the renderer:

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 simultaneously:

• Each renderer page within each window must initialize the RUM SDK.
• When using sessionPersistence: 'local-storage', there may be minimal delays in localStorage synchronization between multiple windows.
• If a large number of windows are created immediately after initialization, very short temporary sessions may appear. It is recommended to leave at least a few tens of milliseconds between window creation and initialization, or create windows sequentially according to business logic.

Local Pages and Remote Pages¶

Electron applications commonly have two page sources:

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 perform correlation analysis using unified user.id, service, env, and version fields.

datafluxRum.setUser({
  id: currentUserId,
  name: currentUserName
})

API Requests and Trace Propagation¶

fetch and XMLHttpRequest in the renderer are automatically collected according to browser SDK logic. If you need to inject Trace Headers into backend API requests, configure allowedTracingUrls:

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: 'ddtrace'
})

Do not include file:// page addresses in allowedTracingUrls. This configuration is for matching backend API requests, not the renderer pages themselves.

Errors and SourceMap¶

Error stacks for Electron local pages often start with file://, and the server may not be able to match SourceMaps directly as it can with public URLs. Recommendations:

• Keep service, env, version, and build artifact versions consistent.
• Generate SourceMaps for renderer artifacts and save them according to the release version.
• If you need to rewrite local file paths, you can add business context in beforeSend for easier subsequent retrieval.

datafluxRum.init({
  // ...
  beforeSend: (event) => {
    if (event.type === 'error') {
      event.context = {
        ...event.context,
        electron: true,
        rendererUrl: window.location.href
      }
    }
    return true
  }
})

CSP and Worker¶

If Session Replay, compressIntakeRequests, or canvas recording is enabled, the SDK may use Workers. If the Electron application has strict CSP configured, it needs to allow the corresponding Worker origins.

Default inline Workers typically require:

worker-src blob:;

If blob: is not allowed, package the worker file as an application static resource and configure the same-origin address:

datafluxRum.init({
  // ...
  workerUrl: './worker.js',
  replayCanvasWorkerUrl: './canvas-worker.js'
})

If using @cloudcare/browser-rum-slim, this package does not include Session Replay and compressIntakeRequests compression capabilities, so generally no worker configuration is needed for these features.

Security Recommendations¶

• Do not expose RUM tokens or other sensitive configuration write interfaces in the main process.
• preload should only expose necessary read-only information, such as application version, channel, and build number.
• Maintain contextIsolation: true and nodeIntegration: false.
• Do not report local file absolute paths, user home directories, or other sensitive information in beforeSend.
• Sanitize user input, filenames, paths, and other fields before writing them to custom context.

Verification Methods¶

After integration, verify in the following order:

1. Open the target window of the Electron application.
2. Confirm RUM reporting requests exist in DevTools Network.
3. Trigger a page view, button click, API request, and frontend error.
4. Confirm that view, action, resource, and error data enters Guance.
5. Check if sessions for the same user across multiple windows or when switching between local/remote pages meet expectations.

During local debugging, you can temporarily enable beforeSend to log event types:

datafluxRum.init({
  // ...
  beforeSend: (event) => {
    console.log('[RUM]', event.type, event)
    return true
  }
})

Frequently Asked Questions¶

Why is there no data from the main process?¶

The RUM SDK is a browser-side SDK and only collects page behavior within the renderer process. Crashes, IPC, filesystem, or native module errors in the main process need to be handled by the application's own logging or crash collection solution.

Why is there no session for file:// pages?¶

Usually, it's because sessionPersistence: 'local-storage' is not configured, or localStorage is disabled in the renderer page environment. First, confirm this configuration and localStorage availability.

Why does the session change after navigating from a local page to a remote page?¶

file:// and https:// belong to different origins; browsers do not share the same cookies or localStorage. It is recommended to set a stable user ID with setUser() and correlate by user during analysis.

Why do very short sessions appear in multiple windows?¶

When multiple windows are initialized simultaneously, there may be minimal delays in localStorage synchronization between windows. It is recommended not to create and initialize a large number of windows at the exact same moment; leave brief intervals between window creation.

Reference Materials¶

• Electron: Process Model