rrweb cloud

Appearance

JavaScript SDK ​

To get started, you'll need a public API key from your rrweb Cloud dashboard.

Basic snippet: set & forget ​

Insert the following HTML snippet into every page of your website (e.g. using your website's master or root template). The code snippet can go between the opening and closing <head> tags.

html
<script src="https://rrwebcloud.com/record.js" autostart async>
  {
    "publicAPIkey": "your-public-api-key-here"
  }
</script>

If you omit the async attribute, the script will block page loading, which is normally not what you want; in any case rrweb will still need to wait until the DOM is ready to before starting recording.

The autostart attribute causes the recording to start as soon as the page is ready. See Manual start for how to start if that's off.

The default connection method is to stream events over websockets to the https://api.rrwebcloud.com/ endpoint; see the serverUrl config parameter below. The script also uses the POST endpoint as a fallback for environments where websockets are unavailable, or if the websocket connection is interrupted e.g. on page unload.

Authentication Required

The publicAPIkey parameter is required for authentication. You can obtain your API key from your rrwebCloud dashboard. This key is used to identify your tenant and ensure proper data isolation.

For WebSocket connections: Since browsers cannot send custom headers with WebSocket requests, the SDK automatically appends your API key as a query parameter (?token=your-api-key) to the WebSocket URL.

Customizing config ​

To supply your own config, add a config argument to the start method. In JS/HTML with autostart on, you can also specify a JSON object within the <script> body. This can be used to configure rrwebCloud, supply application metadata and pass any custom rrweb config.

rrwebCloud options ​

  • publicAPIkey (required): Your public API key for authentication. This key identifies your tenant and ensures proper data isolation. Obtain this from your rrwebCloud dashboard.
  • serverUrl: a custom URL to use instead of the default rrwebCloud endpoint. Not usually needed unless you are serving from an environment where you need to explicitly set the standard rrwebCloud endpoint, or if you are proxying the rrweb endpoints. The special {recordingId} string in the URL will get replaced by the current recordingId before use.
  • includePii (default: false): whether to include meta analytics data (which is potentially personally identifiable). See the Pre-baked metadata guide for more info.
  • autostart (default: false): only relevant for the JS/HTML script tag, whether to call the start method immediately to start recording as soon as the page is ready
html
<script src="https://rrwebcloud.com/record.js" async>
  // some custom config which will be read by record.js
  {
    // REQUIRED: your public API key
    "publicAPIkey": "your-public-api-key-here",

    // the following url is already baked in:
    "serverUrl": "https://rrwebcloud.com/recordings/{recordingId}/ingest/ws",

    // equivalent to the autostart attribute
    "autostart": true,
  }
</script>

Application metadata ​

See the Application metadata guide. If you have application metadata ready to go at page load time, you can provide a meta object in the starting config. This is usually used to associate key value pairs with the recording so that it can later be retrieved in a way which is meaningful in your application.

See also the rrwebCloud.addMeta method if you need to associate this data after the recording has already started, and the Application metadata guide also shows how to associate this data server side without exposing it to the frontend.

html
<script src="https://rrwebcloud.com/record.js" async>
  // some custom config which will be read by record.js
  {
    // REQUIRED: your public API key
    "publicAPIkey": "your-public-api-key-here",

    // rrwebCloud options can be mixed in
    "serverUrl": "...",

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

Overriding rrweb config ​

See the standard rrweb documentation for a full list of configuration options. We've already picked sensible defaults for some of these to suit how we are storing and playing back recordings, so normally you shouldn't have to modify anything.

html
<script src="https://rrwebcloud.com/record.js" async>
  {
    // REQUIRED: your public API key
    "publicAPIkey": "your-public-api-key-here",

    // rrwebCloud options can be mixed in
    "serverUrl": "...",
    "meta": {...},

    // following are standard rrweb config options
    // we've already picked sensible defaults for these
    "blockSelector": ".my-block-class",
    "captureAssets": {
      "video": false,
      "audio": false
    }
  }
</script>

The global rrwebCloud object ​

The rrwebCloud object can be used to associate your own app state with the recording, as well as to retrieve internal details such as the recording id:

rrwebCloud.start() ​

Starts a recording including setting up websocket connections. Equivalent to the rrweb.record function.

See the below section JS/HTML: Manual Start for examples of using start when the autostart attribute is not in use

rrwebCloud.getRecordingId() ​

Every recording made by rrwebCloud is associated with a recordingId which is stored in browser sessionStorage. These can be thought of as internal IDs to rrwebCloud, and their association with sessionStorage is important to distinguish between tabs in a multi-tab browsing session.

If you call getRecordingId() before start() then it will go ahead and create an id which will subsequently be used when the recording starts. If the recordingId is null, then no session recording is possible, as this is the primary key used to store the recording server side.

html
<script>
  if (rrwebCloud) {
    let recordingId = rrwebCloud.getRecordingId();
    if (recordingId) {
      console.log(`
recording can be retrieved from
https://api.rrwebcloud.com/recordings/${recordingId}/events }
      `);
    } else {
      console.log(`recording not possible due to sessionStorage restrictions`);
    }
  } else {
    // see `rScriptEl.addEventListener` example below
  }
</script>

rrwebCloud.addMeta() ​

addMeta is used to associate keys/values with a recording. These can later be used when retrieving lists of recordings. See also the equivalent API POST endpoint: /meta

If you call addMeta multiple times, key values will be added, or values will be updated if the key is already present.

html
<script>
  if (window.rrwebCloud) {
    // this can be called as soon as your app retrieves state.
    rrwebCloud.addMeta({
      user_id: "user-123",
      org_id: "org-9",
      plan: "pro",
      environment: "production",
    });
  } else {
    // see `rScriptEl.addEventListener` example below
  }
</script>

rrwebCloud.stop() ​

The stop method will immediately stop the underlying rrweb library (using stopFn), and also disconnect the websocket connection. It's possible to call rrwebCloud.start() again on the same page, which will kick off with a new rrweb FullSnapshot event and continue the recording.

rrwebCloud.stop(true) ​

Calling the stop function with a single true argument will also erase the recordingId from localStorage. This means if you subsequently call rrwebCloud.start() it will be stored at a fresh recordingId. A stop and start like could be useful to delineate a change of session, if you are assigning session ids via metadata, and want to ensure that a new session starts with a FullSnapshot.

JS/HTML: Manual Start ​

If you omit the autostart attribute on the script tag (or equivalently, set "autostart": false in the config), you can start at a later point using the global window.rrwebCloud object, so long as the script has completed loading. In the following HTML example, we are making sure of the presence of rrwebCloud by attaching to the script onload event:

html
<script src="https://rrwebcloud.com/client.js" id="rScriptEl" async></script>
<script>
  const myStart = () => {
    // check your own app state here to decide whether to start
    rrwebCloud.start({
      publicAPIkey: "your-public-api-key-here", // REQUIRED
      serverUrl: "https://your-custom-endpoint.com/",
      includePii: true,
    });
  };
  if (window.rrwebCloud) {
    // it's already loaded, event listener below would never fire
    myStart();
  } else {
    // we have probably set `async` attribute
    rScriptEl.addEventListener("load", myStart);
  }
</script>