Electron SDK advanced configuration

This page covers optional settings and public APIs for the main-process @flashcatcloud/electron-sdk. The renderer uses the Browser SDK; see Web SDK advanced configuration for its general options.

Initialization options

main.ts

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

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');
}

Option	Type	Required	Default	Description
`applicationId`	`string`	Yes	—	RUM application ID
`clientToken`	`string`	Yes	—	Client Token
`service`	`string`	Yes	—	Service name; use the same value when uploading source maps
`site`	`string`	No	`browser.flashcat.cloud`	Upload host for regular RUM events; enter a host without a protocol or path
`proxy`	`string`	No	—	Custom forwarding endpoint for regular RUM events
`env`	`string`	No	—	Environment. Main-process RUM events do not currently contain this field; configure it separately in the renderer
`version`	`string`	No	—	Application version; use the same value when uploading source maps
`telemetrySampleRate`	`number`	No	`20`	SDK telemetry sample rate from 0–100; set it to `0` to disable telemetry
`batchSize`	`'SMALL' \| 'MEDIUM' \| 'LARGE'`	No	`MEDIUM`	Batch size for regular RUM events
`uploadFrequency`	`'RARE' \| 'NORMAL' \| 'FREQUENT'`	No	`NORMAL`	Upload interval for regular RUM events
`defaultPrivacyLevel`	`'mask' \| 'allow' \| 'mask-user-input'`	No	`mask`	Replay privacy level used when the renderer does not set one
`allowedWebViewHosts`	`string[]`	No	`[]`	Additional hosts allowed to use the bridge; the current window does not need to be listed
`correctPrewarmedViewTimings`	`boolean`	No	`true`	Corrects FCP and LCP for pre-created hidden windows
`normalizeStackPaths`	`boolean`	No	`true`	Rewrites stack paths under the application directory to stable `app:///` paths
`normalizeStackPath`	`(path: string) => string \| undefined`	No	—	Custom mapping for an individual stack frame path

init() returns false when validation fails. The SDK prints the reason in the main-process console and does not start collection, but it does not prevent the application from starting.

Custom upload endpoints

By default, the main process uploads regular RUM events to Flashduty SaaS. You do not need to set site or proxy.

Scenario	Configuration
Flashduty SaaS	No additional configuration
Self-hosted HTTPS intake at `/api/v2/rum`	Set `site` in the main process
Custom path, gateway, or forwarding service	Set `proxy` in the main process
Self-hosted deployment with Session Replay	Also set `proxy` in the renderer

Use a self-hosted intake host

If your intake supports HTTPS and receives events at /api/v2/rum, set its host in site. Do not include https:// or a path:

main.ts

await init({
  // Other options
  site: 'rum.example.internal',
});

The SDK uploads regular RUM events to https://rum.example.internal/api/v2/rum.

Use a custom forwarding endpoint

Use proxy when:

The intake only supports HTTP.
The upload path is not /api/v2/rum.
Clients must access the intake through a shared gateway.

main.ts

await init({
  // Other options
  proxy: 'https://rum-gateway.example.internal/forward',
});

In this configuration, proxy is a RUM forwarding endpoint that you provide, not an operating-system or Electron network proxy. The main process adds the target path to the request. Your forwarding service must preserve the request body and DD-API-KEY header and send the request to the Flashduty intake. After you set proxy, the main process no longer uses site to build the upload URL.

Configure a self-hosted Session Replay endpoint

Regular RUM events go through the main process, but the renderer uploads Session Replay directly. As a result, the main-process site or proxy does not apply to replay segments. For self-hosted Session Replay, set the Browser SDK proxy in the renderer:

renderer.ts

flashcatRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  clientToken: '<YOUR_CLIENT_TOKEN>',
  service: 'my-electron-app',
  proxy: 'https://rum-gateway.example.internal/forward',
  sessionReplaySampleRate: 100,
  sessionReplayDirectUpload: true,
});

Also add this endpoint to the page CSP connect-src directive.

Upload batching and frequency

The main process writes regular RUM events to the application’s userData directory before uploading them in batches. A batch is deleted only after a successful upload.

`batchSize`	Batch size
`SMALL`	16 KiB
`MEDIUM`	512 KiB
`LARGE`	4 MiB

`uploadFrequency`	Upload interval
`RARE`	30 seconds
`NORMAL`	10 seconds
`FREQUENT`	5 seconds

During integration testing, use batchSize: 'SMALL' and uploadFrequency: 'FREQUENT' to see events sooner. Keep the defaults for normal operation.

Disk buffering and retry apply only to regular RUM events. The renderer uploads Session Replay directly, so replay does not use the main-process disk buffer.

Collect third-party pages

The current window’s page can always use the bridge; you do not need to set allowedWebViewHosts for it. Add hosts only when you want to collect a third-party page loaded in a <webview> or BrowserView:

main.ts

await init({
  // Other options
  allowedWebViewHosts: ['partner.example.com'],
});

Matching includes subdomains. For example, allowing example.com also allows app.example.com.

Identify the signed-in user

After sign-in, call setUser() in the main process. Main-process events and bridged renderer events will carry the same user identity.

main.ts

import { clearUser, getUser, setUser } from '@flashcatcloud/electron-sdk';

setUser({
  id: 'user-123',
  name: 'Alice',
  email: 'alice@example.com',
});

console.log(getUser());

// When the user signs out
clearUser();

Field	Required	Description
`id`	Yes	Unique user identifier
`name`	No	User name
`email`	No	User email

When Session Replay is enabled, also call flashcatRum.setUser() and flashcatRum.clearUser() in the renderer as part of the same sign-in and sign-out flow, because replay segments bypass the main process.

Report handled errors

An exception caught by try/catch in the main process is not reported as an unhandled error. Call addError() to record it:

main.ts

import { addError } from '@flashcatcloud/electron-sdk';

try {
  await syncWorkspace();
} catch (error) {
  addError(error, {
    context: {
      component: 'sync',
      workspaceId: 'ws-1001',
    },
  });
}

Manually reported errors are marked as handled. Use properties in context to filter and identify the business workflow.

End the current session

Call stopSession() when a user signs out or when you need to start a new session:

main.ts

import { stopSession } from '@flashcatcloud/electron-sdk';

stopSession();

The current session ends immediately. The next valid UI input creates a new session.

Performance metrics for pre-created windows

Electron applications can create a hidden BrowserWindow, load its page, and show it later. By default, the SDK rebases FCP and LCP on the first time the window becomes visible so the pre-warm delay is not counted as page performance. To keep the raw document Paint Timing values, disable correction:

main.ts

await init({
  // Other options
  correctPrewarmedViewTimings: false,
});

This correction applies only to BrowserWindow. It does not correct metrics from WebContentsView or <webview>.

Customize error stack paths

By default, the SDK rewrites stack paths under the application directory to app:///<relative path>, allowing one source map upload to match installations on different machines. Most applications do not need to change this behavior. If your build output layout does not match the application directory, use normalizeStackPath:

main.ts

await init({
  // Other options
  normalizeStackPath: (absolutePath) => {
    const normalized = absolutePath.replace(/\\/g, '/');
    const match = /\/public(\/dist\/.+)$/.exec(normalized);
    return match ? match[1] : undefined;
  },
});

When the callback returns undefined, the SDK applies its default normalization. See Electron error symbolication for upload instructions.

SDK integration

Instrument the main and renderer processes.

Error symbolication

Upload JavaScript source maps and native crash symbols.

Data collection

Review collected data types and upload behavior.

Troubleshooting

Diagnose bridge, replay, and upload issues.

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Electron SDK advanced configuration

Initialization options

Custom upload endpoints

Use a self-hosted intake host

Use a custom forwarding endpoint

Configure a self-hosted Session Replay endpoint

Upload batching and frequency

Collect third-party pages

Identify the signed-in user

Report handled errors

End the current session

Performance metrics for pre-created windows

Customize error stack paths

SDK integration

Error symbolication

Data collection

Troubleshooting

​Initialization options

​Custom upload endpoints

​Use a self-hosted intake host

​Use a custom forwarding endpoint

​Configure a self-hosted Session Replay endpoint

​Upload batching and frequency

​Collect third-party pages

​Identify the signed-in user

​Report handled errors

​End the current session

​Performance metrics for pre-created windows

​Customize error stack paths

​Related pages

SDK integration

Error symbolication

Data collection

Troubleshooting

Initialization options

Custom upload endpoints

Use a self-hosted intake host

Use a custom forwarding endpoint

Configure a self-hosted Session Replay endpoint

Upload batching and frequency

Collect third-party pages

Identify the signed-in user

Report handled errors

End the current session

Performance metrics for pre-created windows

Customize error stack paths

Related pages