rrweb docs
rrwebDocs

English

简体中文

English

简体中文

Optional visitor metadata ​

The Browser Client's includePii option is false by default. When false, the client does not add the visitor fields below. Enable it only after deciding that you have an appropriate purpose, consent or other legal basis, access controls, and retention period for this data.

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

start({
  publicApiKey: 'public_key_rr_your_key',
  includePii: true,
});

Fields collected when enabled ​

The current Browser Client and ingest service add these fields:

  • visitor: a random browser visitor identifier stored in the first-party rrweb-browser-client-visitor-id cookie.
  • timezone: the browser's resolved IANA timezone, or unknown when it cannot be read.
  • language: the first browser language preference, or unknown when it cannot be read.
  • screenWidth and screenHeight: physical screen dimensions reported by the browser, distinct from rrweb's replay viewport.
  • devicePixelRatio: the ratio between CSS pixels and device pixels.
  • title: the document title attached to rrweb Meta events, truncated to 500 characters.
  • referrer: the document referrer attached to rrweb Meta events.
  • remoteAddress: the connecting IP address added by the ingest service when includePii is true. A proxy or privacy relay can make it imprecise.

The visitor cookie is set with a lifetime of 366 days (approximately one year), SameSite=Lax, the current first-party domain, and Secure on HTTPS pages. Browsers or users may remove it sooner. Do not treat it as a durable identity or as proof that two people are the same user.

The client also sends operational metadata such as the page domain, includePii state, recorder version, entrypoint, and optional script source. Those diagnostics are not enabled by the includePii switch and should not be confused with the visitor fields above.

Reserved names and merge behavior ​

In Browser Client 2.1.0, values from the user-supplied meta object are merged after the automatic visitor fields. Custom metadata can therefore override reserved names such as includePii, domain, visitor, timezone, language, screenWidth, screenHeight, and devicePixelRatio before ingestion.

As a result, includePii: false is not a safe guarantee when meta contains reserved keys. For example, meta: { includePii: true } can make the ingest service add remoteAddress, even when the top-level client option was false. Treat the built-in names as reserved, prefix application metadata (for example, app_user_id), and validate metadata keys before passing them to start() or addMeta().

The ingest service also derives request metadata independently of includePii:

  • ingestOrigin is stored from the browser's Origin header when that header is present.
  • ingestReferer is stored from the browser's Referer header when that header is present.

These server-derived values are stored regardless of includePii and replace client-supplied values with the same names. A browser may omit either header. Referrer-Policy can omit the Referer header or reduce it to an origin; a permissive policy can expose a path or query string. Choose a policy that does not put sensitive data in ingestReferer, and account for both fields in consent, access, and retention decisions.

Tell users what session capture and visitor metadata are for. Start the Browser Client only after any consent your application requires, and stop capture when that consent is withdrawn. Restrict who can search recordings, choose a retention period, and account for deletion or subject-access requests that may involve the visitor ID or IP address.

Avoid adding direct identifiers merely because metadata is searchable. Prefer an opaque application ID and enrich it in a trusted server environment when necessary. See Application metadata for custom fields.

Metadata is not recorded page content ​

includePii: false does not remove personal data from the recorded DOM, text, inputs, canvas, console logs, network payloads, custom events, user-supplied metadata, or the server-derived request fields described above. It controls only the Browser Client's automatic collection of the optional visitor fields.

Configure blocking and masking independently in Recording and privacy settings, and test the stored replay with representative synthetic content before production rollout.