Recording IDs

A recording ID groups one ordered rrweb event stream and its metadata. Most browser integrations should let the Browser Client manage it.

How does the Browser Client choose a recording ID?

The Browser Client automatically creates a UUID and stores it under rrweb-browser-client-recording-id in sessionStorage. Calling start() or getRecordingId() creates the ID if one does not exist. If browser policy makes sessionStorage unavailable, the client cannot start a recording.

Because sessionStorage is scoped to a tab and origin:

• A separate tab normally gets a separate recording ID, preventing its event stream from being interleaved with another tab.
• Same-origin page navigation in the tab keeps the ID, so consecutive page views can belong to one recording.
• stop(false) stops capture but preserves the ID for a later start() on the same page.
• stop(true) clears the stored ID; the next start() creates a new recording.

There is an opener exception: when a page opens a same-origin tab with an opener, browsers can initialize the new tab's sessionStorage as a copy of the opener's storage. The two stores diverge afterward, but the copied rrweb-browser-client-recording-id can make both tabs begin capture with the same ID.

Open recording-capable links with rel="noopener" or use the noopener feature with window.open(). If your application must retain an opener, reset the copied ID in the new tab before the Browser Client starts:

sessionStorage.removeItem('rrweb-browser-client-recording-id');

Reset only at a deliberate new-tab or session boundary. Removing the ID after capture starts would split the lifecycle unexpectedly.

Use getRecordingId() when application code needs to correlate diagnostics with the current recording. Do not copy one tab's ID into another tab.

To relate recordings across tabs, devices, or login sessions, keep their recording IDs distinct and attach a shared opaque identifier through application metadata.

Manual ingestion

The ingestion paths require a valid UUID v4. Generate one and use it consistently for every event and metadata request of one ordered stream.

If you keep a custom recorder or transport, you must create and preserve the ID yourself.

const storageKey = 'my-app-rrweb-recording-id';
let recordingId = sessionStorage.getItem(storageKey);

if (!recordingId) {
  recordingId = crypto.randomUUID();
  sessionStorage.setItem(storageKey, recordingId);
}

Generate a fresh ID at the recording boundary defined by your product, such as explicit logout, consent withdrawal, or a new support session. Never reuse an ID for unrelated users or parallel event streams. See Migrating from rrweb for authenticated manual ingestion and rollback guidance.