rrweb docs
rrwebDocs

English

简体中文

English

简体中文

Application metadata ​

Application metadata is a set of string key/value pairs attached to a recording. Use it to find related recordings, compose multi-recording replays, and filter by release or rollout context.

Privacy boundary ​

Set a metadata policy before assigning session, visitor, or user identifiers. Prefer opaque identifiers created by your application over names, email addresses, account numbers, or other directly identifying values. Opaque identifiers can still be personal data when your systems can resolve them.

Establish consent or another lawful basis for both recording and metadata linkage. Define access control and limit recording and metadata access to authorized roles, choose a retention period that matches your plan and workspace policy, and support applicable access and deletion requests. When consent is withdrawn, stop recording and stop adding metadata; deleting or unlinking previously collected recordings is a separate lifecycle action.

Metadata supplied to the Browser Client is browser-visible. A user can inspect it in page state or network traffic, and anyone with the public write key can submit browser-authorized writes. Do not place secrets or server-only classifications in browser metadata. Send those from an authenticated trusted server instead.

Tie recordings to a user or session ​

A recording ID keeps browser contexts such as separate tabs distinct. Your own opaque session ID can group several recording IDs into a multi-tab replay. An opaque visitor or user ID can find recordings from the same application identity across sessions or devices.

Adding a user ID after login can retroactively link the earlier, pre-login part of that recording to the authenticated user. That makes activity from before the user logged in discoverable through the later identifier. Include this linkage in your consent, access-control, retention, and deletion decisions; omit the update when that scope is not appropriate.

If your application does not already define these identifiers, see Optional visitor metadata. That opt-in is separate from application metadata and does not make recorded DOM content anonymous.

Keys and values ​

  • Values are stored as strings. Serialize booleans or numbers deliberately and keep their format stable.
  • Submitting the same key for one recording overwrites its earlier value; only the latest value is retained.
  • Use stable names such as app_user_id, app_session_id, environment, app_version, and feature_flag.
  • Keep the schema small and avoid raw free-form user input.

Browser-visible metadata ​

Non-secret application context, at start() or later with addMeta(); secrets and server-only classifications belong in the server path below.

Attach non-secret application context when starting the Browser Client or later with addMeta():

javascript
import { start } from '@rrweb/browser-client';

start({
  publicApiKey: 'public_key_rr_your_key',
  meta: {
    app_user_id: 'usr_7f3b92a1',
    app_session_id: 'ses_019fd6c3',
    environment: 'production',
    app_version: '2026.08.06',
  },
});

The same rules apply when an autostart configuration or addMeta() supplies these values: treat them as visible to the browser.

Set metadata from a trusted server ​

Use a private API key only on a trusted server. This example sends server-only metadata directly to the capture metadata operation with an API-valid recording UUID:

ts
const recordingId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.rrweb.com/recordings/${recordingId}/metadata`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RRWEB_CLOUD_PRIVATE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      support_case_id: 'case_019fd6c3',
      account_segment: 'enterprise',
    }),
  },
);

if (!response.ok) {
  throw new Error(`Metadata write failed: ${response.status}`);
}

Validate that the signed-in operator may update that recording before making the Cloud request. Never return the private API key to the browser.

Route browser metadata writes through your server ​

Proxy the metadata call through a same-origin route where your server authenticates the user, validates ownership, derives server-only fields, and adds the private key before making the Cloud request.

When a browser action should add metadata that your server must authorize or derive, call a same-origin application endpoint. The browser sends only the recording ID and allowed input; your server authenticates the user, validates ownership, derives server-only fields, and then performs the authenticated Cloud request described above.

ts
const response = await fetch('/api/recording-metadata', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recordingId: '550e8400-e29b-41d4-a716-446655440000',
    supportCaseId: 'case_019fd6c3',
  }),
});

if (!response.ok) {
  throw new Error('The application could not attach recording metadata');
}

Do not confuse this same-origin proxy with a direct browser request to the Cloud API: the private credential and authorization checks stay on your server.

Get the current recording ID ​

The Browser Client generates a recording ID when capture starts. Read it with getRecordingId() and send it to your server through an authenticated application request when server enrichment is required. Different tabs receive separate recording IDs; page views can reuse an ID according to the Browser Client lifecycle described in Recording IDs.

Reference ​