Skip to main content
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
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.

Session sampling

Starting with Electron SDK 0.4.0, you can sample sessions. sessionSampleRate sets the share of sessions collected and defaults to 100 (every session):
main.ts
  • Each session is drawn once, in the main process, and the result decides for the renderers too: renderer events reach the intake through the main process over the bridge, and the main process drops the events of sessions it did not select.
  • The sessionSampleRate in the renderer’s flashcatRum.init() does not apply to events sent over the bridge. Set it in the main process only.
  • A session resumed after the application restarts keeps the decision it was created with.
  • Every RUM event carries the sample rate its session was drawn at (_dd.configuration.session_sample_rate), which the platform uses to extrapolate totals.

On-error session capture

With sessionOnError on, sessions the sample rate did not select are not dropped right away. Their events are held in memory and uploaded only if the session reports an error:
main.ts
  • Events from the main process and the renderers alike are held, up to the 60 seconds before the error (also capped at 64 KiB of detail, 200 events, and 50 views). The buffer stays in memory and is never written to disk.
  • At the session’s first error, what is held is uploaded together with the error within a few seconds. The session then reports like any sampled session.
  • When the application may be about to exit (an uncaught main-process exception, before-quit, will-quit, and the process exit event), content already released by an error is written to disk first and uploaded on the next launch. For an uncaught main-process exception to count, register your own uncaughtException listener after await init(...) completes.
  • A session that ends without an error is discarded whole, and nothing is uploaded at quit either.
  • Only errors your application reports count: an error dropped by a renderer’s beforeSend, or one the SDK reports about itself, does not. A native crash counts too, and is reported on the next launch together with the view it happened in.
A captured session reports a session sample rate of 0 and carries session.sampled_for_error: true on its views, so it is counted as itself rather than extrapolated by the sample rate. To filter these sessions, see session_sampled_for_error in the data query syntax guide.
Session Replay is not withheld by on-error session capture. The renderer uploads replay directly, bypassing the main process. With sessionReplayDirectUpload on, the replay of a session held by sessionOnError is uploaded whether or not the session ever reports an error. Do not combine sessionOnError with Session Replay.

Remote configuration

Starting with Electron SDK 0.4.0, the session sample rate, Capture additional sessions on error, and custom configuration keys can be adjusted online on the Application management → Remote Configuration tab in the console, without code changes or a new release. The feature is off by default; enable it when you initialize the main process:
main.ts
When the Allow remote configuration switch in the console’s Electron setup guide is on, the generated main-process initialization code includes this line. Once enabled:
  • The main process requests the configuration at init() and whenever a new session starts; init() does not wait for the request. A received configuration applies from the next new session, and running sessions are unaffected. The exception, as of SDK 0.5.3: setting the sample rate to 0 stops collection in the running session right away, and raising it from 0 resumes collection right away.
  • A value set in the console takes precedence over the initialization value. Values the console does not set, or every value while remote configuration is turned off in the console, fall back to the initialization options.
  • The last accepted configuration is kept in the application’s userData directory, so new sessions after a cold start are drawn with it before the network answers, even offline. The cache applies only to the same intake, application, env, and version.
  • Network failures, timeouts, and unrecognized responses keep the configuration in force; the SDK retries twice shortly afterward.
  • The Electron SDK reads only the session sample rate, Capture additional sessions on error, and custom configuration keys. Session Replay is recorded and sampled by the renderer’s own Browser SDK, which remote configuration does not reach, so replay and trace options do not appear for Electron applications.
  • The renderers need no remote configuration of their own; the main process owns the sessions and their sampling.
The configuration endpoint sits next to the intake at /api/v2/rum/config: https://<site>/api/v2/rum/config when you set site. When you set proxy, the request also goes to proxy, with the target path /api/v2/rum/config carried in the ddforward parameter. For private deployments, make sure your forwarding service allows this path.
Read custom configuration keys with getRemoteConfig(), which returns a copy, or undefined when remote configuration is off, no configuration has been received yet, or the console set none. Until the server answers, it reads from the cache on disk, so you can call it as soon as init() resolves:
main.ts
Custom configuration keys are delivered to clients, and anyone holding the Client Token can read them. Never put secrets, access tokens, or personally sensitive information in them.
For the console-side options, publishing, and activation, see Application management · Remote configuration.

Custom upload endpoints

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

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