Electron SDK integration

An Electron application has a main process and one or more renderer processes. After you instrument both sides, you can view desktop runtime activity and page experience in the same RUM session.

Process	SDK	Primary data collected
Main process	`@flashcatcloud/electron-sdk`	Sessions, main-process errors, native crashes, and main-process network requests
Renderer process	`@flashcatcloud/browser-rum`	Page views, user actions, frontend resources, JavaScript errors, and Web Vitals

Regular renderer events are forwarded to the main process and uploaded together with main-process events. You do not need to write custom IPC forwarding code.

Prerequisites

Before you start, make sure that:

Your application uses Electron 39 or later.
You created or selected an Electron application on the Flashduty RUM application management page and obtained its Application ID and Client Token.
The application can reach https://browser.flashcat.cloud/api/v2/rum. For a self-hosted deployment, prepare your own intake endpoint.

Integration steps

Install the SDKs

Install the main-process SDK and Browser SDK in your project:

npm install @flashcatcloud/electron-sdk @flashcatcloud/browser-rum@^0.0.7

Use @flashcatcloud/browser-rum 0.0.7 or later to enable Session Replay in Electron.

Configure the main-process entry point

The Electron SDK must start instrumentation before Electron loads. Choose the setup that matches how you build the main process.

Unbundled main process
Vite
Webpack
esbuild

Make instrument the first import in the main-process entry point:

main.ts

import '@flashcatcloud/electron-sdk/instrument';

import { app, BrowserWindow } from 'electron';

If your project sorts imports automatically, make sure it does not move this import after electron.

Add the plugin to the main-process Vite configuration. In an electron-vite project, use the main configuration, not renderer.

vite.config.ts

import { defineConfig } from 'vite';
import { datadogVitePlugin } from '@flashcatcloud/electron-sdk/vite-plugin';

export default defineConfig({
  plugins: [datadogVitePlugin()],
});

Add the plugin to the main-process Webpack configuration:

webpack.main.config.js

const { DatadogWebpackPlugin } = require('@flashcatcloud/electron-sdk/webpack-plugin');

module.exports = {
  plugins: [new DatadogWebpackPlugin()],
};

Add the plugin to the main-process build:

build.ts

import * as esbuild from 'esbuild';
import { datadogEsbuildPlugin } from '@flashcatcloud/electron-sdk/esbuild-plugin';

await esbuild.build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  platform: 'node',
  outfile: 'dist/main.js',
  plugins: [datadogEsbuildPlugin()],
});

When you use a bundler plugin, do not manually import @flashcatcloud/electron-sdk/instrument. The plugin handles execution order and runtime dependencies.

Initialize the main-process SDK

Call init() after app.whenReady() and before you create the first BrowserWindow:

main.ts

import { app, BrowserWindow } from 'electron';
import { init } from '@flashcatcloud/electron-sdk';

void app.whenReady().then(async () => {
  const initialized = await init({
    applicationId: '<YOUR_APPLICATION_ID>',
    clientToken: '<YOUR_CLIENT_TOKEN>',
    service: 'my-electron-app',
    env: 'production',
    version: app.getVersion(),
  });

  if (!initialized) {
    console.error('[Flashduty RUM] SDK initialization failed');
  }

  createWindow();
});

function createWindow(): void {
  const window = new BrowserWindow();
  void window.loadFile('index.html');
}

applicationId, clientToken, and service are required. Flashduty SaaS users do not need to set site. Initialization failure does not prevent the application from starting; the SDK logs the specific reason in the main-process console.

Initialize the renderer SDK

Initialize the Browser SDK in the renderer entry point:

renderer.ts

import { flashcatRum } from '@flashcatcloud/browser-rum';

flashcatRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  clientToken: '<YOUR_CLIENT_TOKEN>',
  service: 'my-electron-app',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  trackResources: true,
  trackLongTasks: true,
  trackUserInteractions: true,
});

Use the same applicationId, clientToken, service, env, and version in both processes so one application is not split across different dimensions.After the main process is configured, the SDK injects its preload and establishes the bridge automatically. You do not need to modify your application’s preload or write ipcRenderer / ipcMain forwarding code. Use allowedWebViewHosts only for third-party pages loaded in a <webview> or BrowserView.

Verify the integration

Start the application, visit a page, click an element, and make a network request. Then verify the data in RUM Explorer:

Filter all Electron events with source:electron OR container.source:electron.
Confirm that main-process events appear with view.url: electron://main-process.
Confirm that renderer view, action, resource, or error events appear.
Check that renderer events contain container.source: electron.

The default upload interval is 10 seconds. Wait for one upload cycle before refreshing the Explorer.

The integration is working when the same session contains main-process and renderer events, and renderer events include container.source: electron.

Enable Session Replay (optional)

The renderer records and uploads Session Replay directly. Set both the sample rate and direct-upload option in the renderer configuration:

renderer.ts

flashcatRum.init({
  // Other options from the previous example
  sessionReplaySampleRate: 100,
  sessionReplayDirectUpload: true,
  defaultPrivacyLevel: 'mask',
});

Replay recording creates a blob Worker and connects to the intake from the renderer. If your page defines a Content Security Policy (CSP), allow worker-src blob: and the actual intake origin:

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self';
  worker-src 'self' blob:;
  connect-src 'self' https://browser.flashcat.cloud;
">

For self-hosted Session Replay, configure proxy separately in the renderer. See Advanced configuration · Custom upload endpoints. If no replay is collected, see Electron SDK troubleshooting.

Next steps

Advanced configuration

Configure custom upload endpoints, batching, user identity, and manual APIs.

Data collection

Learn what the main and renderer processes collect.

Error symbolication

Upload JavaScript source maps and native crash symbols.

Troubleshooting

Diagnose bridge, Session Replay, and stack symbolication issues.

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Prerequisites

Integration steps

Enable Session Replay (optional)

Next steps

Advanced configuration

Data collection

Error symbolication

Troubleshooting

​Prerequisites

​Integration steps

​Enable Session Replay (optional)

​Next steps

Advanced configuration

Data collection

Error symbolication

Troubleshooting

Prerequisites

Integration steps

Enable Session Replay (optional)

Next steps