rrweb docs
rrwebDocs

English

简体中文

English

简体中文

@rrweb/browser-client ​

Overview ​

Browser client for recording rrweb sessions to an rrweb Cloud-compatible API. It wraps rrweb recording, streams events over WebSocket, and falls back to HTTP POST for buffered events.

This README covers the npm/ESM package. For the hosted script snippet and broader rrweb Cloud setup, see the JavaScript SDK guide.

Installation ​

bash
npm install @rrweb/browser-client

Quick Start ​

js
import rrwebBrowserClient, {
  start,
  stop,
  addMeta,
  getRecordingId,
} from '@rrweb/browser-client';

start({
  publicApiKey: 'public_key_rr_...',
  includePii: false,
  meta: {
    userId: 'user-123',
    environment: 'production',
  },
});

addMeta({ plan: 'pro' });

console.log('recording id', getRecordingId());
stop(false);

The default export exposes the same methods:

js
rrwebBrowserClient.start({
  publicApiKey: 'public_key_rr_...',
});

Options ​

  • serverUrl: optional events endpoint. Defaults to https://api.rrweb.com/recordings/{recordingId}/events/ws. Include {recordingId} in custom URLs, or the client will add it as a query parameter. http and https URLs are converted to ws and wss for the WebSocket connection, and the HTTP fallback posts to the same endpoint without a trailing /ws. See Recording endpoint proxying when routing events through your own domain.
  • publicApiKey: public write-only API key sent with WebSocket and HTTP fallback requests. rrweb Cloud public keys use the public_key_rr_... format. See API Keys.
  • includePii: default false. When enabled, the client includes additional visitor metadata such as language, timezone, screen size, title, and referrer details. See Pre-baked metadata.
  • meta: custom recording metadata sent before recorded events. Built-in diagnostics such as recordVersion, recordCommitHash, jsSource, and jsEntrypoint are added automatically after custom metadata. See Application Metadata.
  • jsSource: optional source identifier for programmatic loaders. URL values are recorded without query strings or hashes.
  • jsEntrypoint: optional entrypoint label. Defaults to programmatic for direct start() calls and script-tag for script-tag autostart.
  • rrweb record options: other options are passed through to record() from rrweb, such as masking, blocking, sampling, and DOM capture options. See the rrweb recording docs.

Stylesheet Capture ​

inlineStylesheet is currently used for stylesheet capture compatibility. Once the captureAssets recording API lands from the assets branch, captureAssets.stylesheets should replace that compatibility path.

Recording Helpers ​

  • getRecordingId(): returns the current recording id, creating it before start() if needed. Recording ids are stored in sessionStorage, so separate tabs get separate recording contexts.
  • addMeta(payload): adds or updates recording metadata after recording has started.
  • addPageviewMeta(payload): adds metadata for the current page view.
  • addCustomEvent(tag, payload): queues a custom rrweb event.
  • stop(resetRecordingId): stops rrweb recording and closes the WebSocket. Pass true to clear the stored recording id before a future start().

Further Reading ​

Local Dev/Test Env Vars ​

Copy .env.example to .env in this package when running local integration tests.

bash
VITE_RRWEB_BROWSER_CLIENT_SERVER_URL=http://localhost:8787/recordings/{recordingId}/events/ws
VITE_RRWEB_BROWSER_CLIENT_API_BASE_URL=http://localhost:8787
VITE_TEST_API_KEY=public_key_rr_XXXX

Edit README on GitHub

Release Notes for @rrweb/browser-client ​

2.1.1 ​

Patch Changes ​

  • Updated dependencies []:
    • rrweb@2.1.1
    • @rrweb/record@2.1.1
    • @rrweb/types@2.1.1
    • @rrweb/utils@2.1.1

2.1.0 ​

Patch Changes ​

2.0.1 ​

Patch Changes ​

  • Updated dependencies [5f52d63]:
    • rrweb@2.0.1
    • @rrweb/utils@2.0.1
    • @rrweb/record@2.0.1
    • @rrweb/types@2.0.1

2.0.0 ​

Patch Changes ​