Application Metadata

'Application Metadata' refers to a list of key/value pairs that are associated with a recording. You can assign them in the browser as a recording starts (or after it has already started), or directly and privately in your backend via our API at any time post-recording, so long as you have a recording's recordingId.

You can view and filter your recordings by metadata in the rrweb Cloud dashboard.

Primary uses:

• Retrieve lists of related recordings
• Compose separate recordings for replaying together
• Tagging new releases and debugging
• Dashboards for monitoring

Scenario: Assigning your own session ids

rrwebCloud allows you to assign your own session ids to recordings to align with how sessions work in your application/website. We recognize that there is no single definition of a 'session', and instead we maintain a recordingId to keep browsing contexts separate (e.g. separate tabs). A session id that you assign to one or more recordings can be used at retrieval time to produse a single multi-tab replay comprising a number of parallel recordings.

Scenario: Assigning visitor or user ids

Another use case for application metadata is to list recordings which have been tagged with the same value, e.g. list all recordings with a particular user or visitor id, or replay all recordings from the same user when you have identified them across different devices. As a recording can be tagged with a user id after the user has logged in, the replay will be able to show the user's activity before they logged in.

If you don't already have existing definitions of sessions, visitors or users in your app, you can use instruct rrwebCloud to add them as 'pre-baked' metadata.

Treatment of keys/values

• Submitting metadata for the same recording again may overwrite earlier values for matching keys
• Values are stored as strings. We've left out numeric or boolean data types for now pending a client usecase

Sending metadata when creating a recording (visible in browser)

You can add metadata when creating a recording within the browser. These options are covered in Customizing config (specifically, the Application metadata section).

{
  "user_id": "user-123",
  "session_id": "existing-session-id",
  "org_id": "org-9",
  "plan": "pro",
  "environment": "production"
}

You can feed the above JSON example to rrwebCloud in a number of ways:

• using the meta key in your autostart JS/HTML config (the JSON between the start and end <script> tags)
• in the meta key in the config argument of the rrwebCloud.start() method (if autostart is off)
• directly as the argument to rrwebCloud.addMeta() method after the recording has already started in the browser

Sending metadata using the POST endpoint

Use the POST /recordings/{recordingId}/meta endpoint to attach application metadata to any recording for which you have the recordingId. This is useful for information that you don't want to make visible in the browser, as it can be executed serverside from your backend.

Examples

RECORDING_ID="0f2fcf4f-e352-48a8-9029-db4b42a606b6"
RRWEB_CLOUD_TOKEN="..."

curl -X POST "https://api.rrwebcloud.com/recordings/$RECORDING_ID/meta" \
  -H "Authorization: Bearer $RRWEB_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-789",
    "plan": "pro",
    "environment": "production",
    "featureFlags": "new-sidebar"
  }'

Getting the recordingId

The recordingId is generated in the browser by rrwebCloud when a recording is started, and can be retrieved using rrwebCloud.getRecordingId(). Subsequent page views will reuse the same recording id, but different tabs in the same browser will start a new browsing context with a different recordingId. If you intend to use the POST endpoint offline, these ids will need to be sent to your your backend as part of your own browser analytics. Alternatively, when a recording starts, you can immediately assign those identifiers that are already in place (e.g. a session or device id) and use them to later retrieve the recordingId(s), in order to add further metadata offline as that metadata becomes available.

Further considerations and Technical Details

Decide which identifiers, device hints, or business attributes let you regroup the recording later. A lean schema (user id, plan, environment, feature flag, etc.) speeds up ingestion and querying.

Recommended fields

Category	Field	Example	Why it helps
Identity	userId, orgId	user-123, team-9	Jump directly to the impacted customer
Experience	deviceType, browser, appVersion	mobile, Chrome 129	Filter for problematic environments
Business context	plan, region, environment	enterprise, eu-west, staging	Tie recordings to revenue or rollout phases
Attribution	utmSource, campaign, featureFlags	ads, winter-promo, beta	Measure funnels and experiments

Keep keys consistent (camelCase is common) and prefer primitive values over deeply nested blobs. Be mindful of payload size; a few dozen key/values per recording is usually plenty.

Reference

• Application Metadata in the JavaScript SDK set up guide

• rrwebCloud.addMeta method in the same guide

• API metadata POST endpoint