docs(rum): align Electron guide with v0.2.1 behavior

Author: Fiona2016

en/rum/sdk/electron/advanced-config.mdx

@@ -30,7 +30,7 @@ await init({
 | `clientToken` | `string` | Yes | — | Client token |
 | `service` | `string` | Yes | — | Service name; must match the value used when uploading source maps |
 | `site` | `string` | No | `browser.flashcat.cloud` | Reporting site, used directly as the intake host. Self-hosted deployments set their own domain; for a plain-HTTP intake see [When a proxy is required](#when-a-proxy-is-required) |
-| `env` | `string` | No | — | Environment identifier such as `production` or `staging` |
+| `env` | `string` | No | — | Environment identifier such as `production` or `staging`. It currently enters the span envelope, which is not uploaded; main-process RUM events do not carry it. Configure the renderer separately in `flashcatRum.init()` |
 | `version` | `string` | No | — | Application version; must match the value used when uploading source maps |
 | `proxy` | `string` | No | — | Custom reporting endpoint, see [Self-hosted deployments and proxies](#self-hosted-deployments-and-proxies) |
 | `allowedWebViewHosts` | `string[]` | No | `[]` | **Additional** hosts allowed to report through the bridge. A window's own host is always allowed, so configure this only to accept events from third-party pages in a `<webview>` / `BrowserView` |
@@ -179,6 +179,40 @@ import { stopSession } from '@flashcatcloud/electron-sdk';
 stopSession();
 ```
 
+## Identify the signed-in user
+
+Call `setUser()` after sign-in so subsequent main-process events and bridged renderer events carry the same `usr` identity. Call `clearUser()` on sign-out; `getUser()` returns the current identity.
+
+```ts
+import { clearUser, getUser, setUser } from '@flashcatcloud/electron-sdk';
+
+setUser({
+  id: 'user-123',
+  name: 'Alice',
+  email: 'alice@example.com',
+});
+
+console.log(getUser()); // Returns a copy: { id, name, email }
+
+clearUser();
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Non-empty string written to `usr.id` |
+| `name` | No | String written to `usr.name` |
+| `email` | No | String written to `usr.email` |
+
+The SDK accepts only these three fields. If `id` is missing or either optional field is not a string, it ignores the entire call and prints a warning. When a main-process identity exists, it **replaces** the renderer event's `id` / `name` / `email` as a unit instead of merging fields. `usr.anonymous_id` is always preserved so the same device remains identifiable across sign-in states.
+
+<Warning>
+Main-process `setUser()` covers main-process events and regular RUM events forwarded over the bridge, but it does not rewrite Session Replay segments uploaded directly by the renderer. With replay enabled, call renderer-side `flashcatRum.setUser()` / `flashcatRum.clearUser()` in the same sign-in and sign-out flow.
+</Warning>
+
+<Note>
+`clearUser()` affects subsequent events only; it does not rewrite data already reported. The SDK stores point-in-time identity history as plain text in `app.getPath('userData')/_dd_user_history`, allowing a native crash parsed on the next startup to retain the user who was signed in when it occurred. Protect the `userData` directory according to your local-data and privacy policy.
+</Note>
+
 ## Operation monitoring (preview)
 
 Track critical business workflows with paired start and end calls. The backend correlates them by `name` (and an optional `operationKey`) and emits `vital` events.
@@ -209,7 +243,7 @@ failOperation('upload', 'abandoned', { operationKey: 'cover_photo' });
 | `options.context` | Custom attributes merged into the event `context` |
 | `options.description` | Description written to `vital.description` |
 
-Because correlation happens on the backend, an operation **can start in one process and finish in the other** — for example `startOperation` when the renderer's checkout button is clicked, and `succeedOperation` once the main process has placed the order.
+These APIs are provided by the main-process `@flashcatcloud/electron-sdk` package. The currently required `@flashcatcloud/browser-rum` `0.0.7` does not expose matching Operation APIs. If a workflow starts in a renderer, use your application's own preload / IPC surface to call the main-process API, then call the matching completion method in the main process.
 
 <Warning>
 This API is in preview and its signatures may change before the stable release.
@@ -364,13 +398,16 @@ The built-in normalization treats the application root as the single anchor. Whe
 await init({
   // …
   normalizeStackPath: (absolutePath) => {
+    // The callback receives the raw frame URL before built-in normalization;
+    // normalize Windows separators first.
+    const framePath = absolutePath.replace(/\\/g, '/');
     // …/public/dist/renderer.js → /dist/renderer.js (swallow the intermediate public/ segment)
-    const emitted = /\/public(\/dist\/.+)$/.exec(absolutePath);
+    const emitted = /\/public(\/dist\/.+)$/.exec(framePath);
     if (emitted) {
       return emitted[1];
     }
     // a linked internal package, kept relative to the application root
-    const linked = /(\/node_modules\/@acme\/widgets\/dist\/.+)$/.exec(absolutePath);
+    const linked = /(\/node_modules\/@acme\/widgets\/dist\/.+)$/.exec(framePath);
     return linked ? linked[1] : undefined; // everything else → the built-in app:///
   },
 });
@@ -426,7 +463,7 @@ stack.replace(
 );
 ```
 
-When you do need custom mapping, prefer [`normalizeStackPath`](#custom-path-mapping): it receives an absolute path that is already unified across platforms, and it applies to both processes.
+When you do need custom mapping, prefer [`normalizeStackPath`](#custom-path-mapping), which applies to both processes. The callback receives the **raw frame URL before built-in processing**; it may contain `file://`, percent escapes, or Windows backslashes, so your mapping must handle the path forms your application emits.
 </Warning>
 
 <Note>

en/rum/sdk/electron/compatible.mdx

@@ -29,7 +29,7 @@ This page describes the Electron SDK support scope and current limits so you can
 | Other bundlers | No plugin | You must guarantee the instrument entry point runs before `require('electron')` and keep `dd-trace` and the SDK external |
 
 <Warning>
-When the main process is bundled, the matching plugin is **required**. Otherwise the bundler's `require` hoisting breaks the `dd-trace` module hook order: the SDK still initializes and reports main-process data, but `BrowserWindow` preload injection fails and renderer processes never receive the bridge object.
+When the main process is bundled, the matching plugin is **required**. It preserves the instrument entry order, keeps `dd-trace` and the SDK as runtime dependencies, and copies the SDK's own preload into the packaged output; missing any of these steps can break main-process network tracing or the renderer bridge. The Electron SDK registers its preload per `session`; this does not depend on `dd-trace` wrapping `BrowserWindow`.
 </Warning>
 
 ## Renderer page loading
@@ -52,6 +52,7 @@ A window's own host is always on the bridge allowlist, so **every loading method
 | Main-process view | Supported | One view per main-process instance |
 | Node uncaught exceptions / promise rejections | Supported | `process.on('uncaughtException' \| 'unhandledRejection')` |
 | Main-process HTTP requests | Supported | Traced by `dd-trace` for `http`/`https`, `fetch`, and `net.fetch`, converted to `resource` |
+| Signed-in user identity | Supported | The main process exposes `setUser` / `getUser` / `clearUser` and attaches identity to main-process and bridged renderer events |
 | Native crash capture | Supported | Electron `crashReporter` writes minidumps, parsed and uploaded on the next startup |
 | Renderer / child process terminations | Supported | Listens for `render-process-gone` / `child-process-gone`, covering terminations that produce no dump |
 | Native crash symbolication | Supported | Requires uploading Breakpad symbol files, see [Upload native crash symbols](/en/rum/sdk/electron/advanced-config#upload-native-crash-symbols) |
@@ -72,7 +73,9 @@ A window's own host is always on the bridge allowlist, so **every loading method
 | APM / distributed tracing | Flashduty has no span intake today. IPC and child-process command spans collected by `dd-trace` are dropped locally; only HTTP spans become RUM `resource` events |
 | Log reporting | Log-type events sent over the bridge from renderers are not forwarded to the backend in this version |
 | Main-process Web Vitals | The main process is a Node.js runtime with no DOM or rendering pipeline, so it produces no LCP / INP / CLS, long task, or user action data. The console hides the performance section for main-process views |
-| Session renewal signal | Only renderer `click` actions extend the session. A purely background main process enters a new session after 15 minutes without interaction |
+| Main-process RUM has no `env` | `env` is currently written only into the span envelope that is not uploaded; it is not attached to main-process RUM events. Renderer events keep the `env` from `flashcatRum.init()` |
+| No renderer Operation API | The currently required `@flashcatcloud/browser-rum` `0.0.7` does not expose `startOperation` / `succeedOperation` / `failOperation`. Renderer-triggered workflows must call the main-process API through the application's own preload / IPC surface |
+| Session renewal signal | Only renderer `webContents` input events `mouseDown`, `mouseWheel`, `keyDown`, and `rawKeyDown` renew the session. Background activity does not; RUM events after expiry are discarded until the next valid input creates a new session |
 | Upload scheme fixed to HTTPS | The `https://` in the `https://<site>/api/v2/rum` template is hardcoded. If a self-hosted intake serves plain HTTP only, changing `site` does not help — use `proxy`. See [Advanced configuration](/en/rum/sdk/electron/advanced-config#when-a-proxy-is-required) |
 | No stack on termination events | `render-process-gone` / `child-process-gone` events carry no call stack — the main process cannot unwind a process that is already gone |
 | Paint metric correction covers `BrowserWindow` only | `WebContentsView` and `<webview>` have no `show` event, so the SDK cannot observe when they become visible and their paint metrics are reported as they are. In addition, the FCP / LCP of a view whose window was never `show()`n are discarded rather than reported — see [Advanced configuration · FCP and LCP of pre-warmed windows](/en/rum/sdk/electron/advanced-config#fcp-and-lcp-of-pre-warmed-windows) |

en/rum/sdk/electron/data-collection.mdx

@@ -5,7 +5,7 @@ description: "Learn which event types, fields, and upload behavior the Electron
 keywords: ["RUM", "Electron SDK", "data collection", "main process", "renderer process", "crash"]
 ---
 
-Electron RUM data comes from two processes and is uploaded by the main process. This page describes what each process collects.
+Electron RUM data comes from two processes. Regular RUM events are uploaded by the main process, while Session Replay segments are uploaded directly by the renderer. This page describes what each process collects.
 
 ## Collection overview
 
@@ -18,7 +18,7 @@ Electron RUM data comes from two processes and is uploaded by the main process.
 | Native crashes (minidump) | Main process | Enabled | `error` (`is_crash: true`) |
 | Renderer / child process terminations | Main process | Enabled | `error` (`is_crash: false`) |
 | Main-process HTTP requests | Main process | Enabled | `resource` |
-| Operation monitoring | Main / renderer | Manual (preview) | `vital` |
+| Operation monitoring | Main process | Manual (preview) | `vital` |
 | Page views, user actions, front-end resources, JS errors, Web Vitals | Renderer process | Enabled | `view` / `action` / `resource` / `error` |
 | SDK internal telemetry | Main process | Enabled (20% sampled) | `telemetry` |
 
@@ -36,19 +36,26 @@ RUM events produced **by the main process itself** are enriched with the followi
 | `source` | Always `electron` |
 | `view.id` | The active view when the event occurred |
 | `view.name` / `view.url` | Always `main process` / `electron://main-process` |
+| `usr.anonymous_id` | Device identifier generated and persisted by the SDK |
+| `usr.id` / `usr.name` / `usr.email` | Signed-in user identity added after `setUser()` is called |
 | `ddtags` | Includes `sdk_version:<SDK version>` |
 | `_dd.format_version` | Always `2` |
 
+<Note>
+Main-process RUM events currently do not carry `env`. The `env` configuration is only written into the span envelope that is not uploaded; renderer events keep the `env` from their own `flashcatRum.init()` configuration.
+</Note>
+
 ## How renderer events are identified
 
-When the bridge is working, the main process does **not** rewrite the `source` of renderer events. It overrides three fields and adds one:
+When the bridge is working, the main process does **not** rewrite the `source` of renderer events. It overrides two fields and adds two; if a main-process user is set, it also replaces the user identity:
 
 | Field | What the main process does |
 |-------|----------------------------|
 | `session.id` | Overridden with the main-process session ID |
 | `application.id` | Overridden with the configured application ID |
 | `container.source` | Added as `electron` |
 | `container.view.id` | Added as the current main-process view ID |
+| `usr` | When `setUser()` has been called, replaces the renderer identity with the main-process `id` / `name` / `email` while preserving `usr.anonymous_id`; otherwise leaves the renderer value unchanged |
 
 The renderer's own `source`, `view`, `service`, and other attributes are preserved. The two kinds of events are therefore identified differently:
 
@@ -62,9 +69,25 @@ Filtering on `source:electron` alone in the Explorer returns **main-process even
 </Warning>
 
 <Note>
-When the bridge is broken (the main process has not integrated the SDK, or it is bundled without the plugin so the preload is never injected), the renderer behaves as a standalone web application and uploads directly: `source` is still `browser`, but there is **no `container` field** and the session is unrelated to the main process. See [What a broken bridge looks like](/en/rum/sdk/electron/sdk-integration#what-a-broken-bridge-looks-like).
+When the bridge is broken (for example, the main process never runs `instrument`, or the packaged application is missing the SDK / preload runtime files), the renderer behaves as a standalone web application and uploads directly: `source` is still `browser`, but there is **no `container` field** and the session is unrelated to the main process. See [What a broken bridge looks like](/en/rum/sdk/electron/sdk-integration#what-a-broken-bridge-looks-like).
 </Note>
 
+## User identity
+
+At startup, the SDK generates `usr.anonymous_id` and stores it at `app.getPath('userData')/_dd_anonymous_id`. This device identifier remains stable across sessions, application restarts, and login state; the main process manages signed-in identity separately through `setUser()`.
+
+| State | `usr` on events |
+|-------|-----------------|
+| Before `setUser()` | Contains only `anonymous_id`; it is not copied into `id` |
+| After `setUser({ id, name?, email? })` | Contains both the device `anonymous_id` and the signed-in user's standard fields |
+| After `clearUser()` | Future events omit `id` / `name` / `email`; `anonymous_id` remains unchanged |
+
+The main process resolves the user at the **time the event occurred**, not when it is uploaded. For example, a native crash parsed on the next startup is still assigned to the user who was signed in when the crash happened. Identity history is stored in `userData/_dd_user_history`; a new process does not automatically restore the previous run's current signed-in user, so call `setUser()` again after confirming login state.
+
+Regular bridged renderer events follow the main-process identity: when the main process has a user, its standard identity fields replace the renderer's; otherwise an identity set through the renderer's `flashcatRum.setUser()` is preserved. Session Replay segments upload directly from the renderer and bypass this step. When Replay is enabled, also call renderer-side `flashcatRum.setUser()` / `flashcatRum.clearUser()` in the login and logout flows.
+
+See [Advanced configuration · Identify the signed-in user](/en/rum/sdk/electron/advanced-config#identify-the-signed-in-user) for the API.
+
 ## Session
 
 The main process owns the session lifecycle. Session state is persisted in the `_dd_s` file under `app.getPath('userData')`, so an unexpired session survives an application restart.
@@ -73,12 +96,14 @@ The main process owns the session lifecycle. Session state is persisted in the `
 |------|-------|
 | Inactivity timeout | 15 minutes |
 | Maximum session duration | 4 hours |
-| Activity signal | `click` actions bridged from the renderer |
+| Activity signal | Electron `webContents` input events: `mouseDown`, `mouseWheel`, `keyDown`, and `rawKeyDown` |
 | On expiry | Sends a final view update with `is_active: false` and deletes `_dd_s` |
 | On renewal | After expiry, the next activity signal creates a new session and a new view |
 
 <Note>
-Only renderer clicks currently extend the session. If your application runs main-process background work for a long time without UI interaction, the session expires after 15 minutes and later main-process events belong to a new session.
+Renewal listens directly to Electron input events; it does not depend on the Browser SDK, bridge status, or `trackUserInteractions`. Mouse movement, pointer entry/exit, and key-up events do not count because they can occur without intentional interaction or already have a corresponding press event.
+
+If the application performs only background main-process work without these UI inputs, the session expires after 15 minutes. RUM events after expiry are discarded until the next valid input creates a new session; background work does not start one by itself.
 </Note>
 
 ## Main-process view
@@ -244,7 +269,9 @@ The main process is a Node.js runtime with no DOM and no rendering pipeline, so
 
 ## Operation monitoring (preview)
 
-`startOperation` / `succeedOperation` / `failOperation` track the start and end of critical business workflows (login, checkout, file upload) and emit `vital` events. The backend correlates start and end steps by `name` and an optional `operationKey`, so an operation **can start in one process and finish in the other**.
+The main-process `startOperation` / `succeedOperation` / `failOperation` APIs track the start and end of critical business workflows (login, checkout, file upload) and emit `vital` events. The backend correlates start and end steps by `name` and an optional `operationKey`.
+
+The currently required `@flashcatcloud/browser-rum` `0.0.7` does not expose matching Operation APIs. For a workflow triggered in a renderer, use your application's own preload / IPC surface to call the main-process API.
 
 | Field | Description |
 |-------|-------------|