Session replay plugin

Overview

This topic documents how to get started with the LaunchDarkly session replay plugin, which is compatible with the LaunchDarkly client-side JavaScript-based SDKs.

The session replay plugin provides a way to record and replay end-user sessions from your application. This plugin does not include any of the error monitoring, logging, or tracing functionality of the observability plugin.

Prerequisites and dependencies

This reference guide assumes that you are somewhat familiar with the LaunchDarkly JavaScript SDK.

The session replay plugin is compatible with the JavaScript SDK, version 3.7.0 and later. It is also compatible with the React Web SDK, version 3.7.0 and later, and the Vue SDK, version 2.4.0 and later.

Most customers who use the session replay plugin also use the observability plugin. However, there is no dependency between the plugins, and you can use only one or the other if you like.

Get started

Follow these steps to get started using the observability plugin:

• Install the plugin
• Initialize the SDK client
• Configure the plugin options
• Explore supported features
• Review session replays in LaunchDarkly

Install the plugin

LaunchDarkly uses a plugin to the JavaScript SDK to provide observability.

The first step is to make both the SDK and the session replay plugin available as dependencies.

The observability plugin is available separately. To learn more, read Observability plugin.

Here’s how:

$
npm install launchdarkly-js-client-sdk
>
npm install @launchdarkly/session-replay

Then, import the plugin into your code:

1
import { initialize } from "launchdarkly-js-client-sdk";
2
import { SessionReplay, LDRecord } from "@launchdarkly/session-replay";

Initialize the client

Next, initialize the SDK and the session replay plugin.

To initialize, you need your LaunchDarkly environment’s client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly. To learn more, read Initialize the client in the JavaScript SDK reference guide.

Here’s how to initialize the SDK and plugin:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
6
const client = initialize('client-side-id-123abc', context, {
7
  plugins: [ new SessionReplay() ]
8
});

You can also initialize the plugin before you initialize the SDK if you like. This may be helpful if you need observability data very early in your application’s lifecycle.

Here’s how:

1
import { SessionReplay, LDRecord } from "@launchdarkly/session-replay";
2
3
LDRecord.init();

Finally, you can optionally register the plugin after you initialize the SDK:

1
import { SessionReplay, LDRecord } from "@launchdarkly/observability";
2
3
LDRecord.register(client);

We do not recommend this option because you will miss observability data generated before you register the plugin.

Configure the plugin options

You can configure options for the session replay plugin when you initialize the SDK if you like. The plugin constructor takes an optional object with the configuration details.

Here is an example:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
6
const client = initialize('client-side-id-123abc', context, {
7
  plugins: [
8
    new SessionReplay({
9
      privacySetting: 'none',
10
        // or 'default' to redact text matching common regex for PII
11
        // or 'strict' to redact all text and images
12
    })
13
  ]
14
});

For more information on plugin options, read Client-side observability.

Set Context-Security-Policy (CSP)

If your application runs in an environment that enforces content security policies, you must set the Content-Security-Policy (CSP) in your application to tell the browser how your page can interact with third-party scripts.

Here are the policies you need to set to use the session replay plugin:

• connect-src: https://pub.observability.app.launchdarkly.com https://otel.observability.app.launchdarkly.com: This policy allows connecting with LaunchDarkly servers to send recorded session data.
• worker-src: data: blob:: This policy allows creating an inlined web worker initialized by the npm package for this plugin.

Your CSP definition may look something like this:

1
<meta
2
  http-equiv="Content-Security-Policy"
3
  content="connect-src: https://pub.observability.app.launchdarkly.com https://otel.observability.app.launchdarkly.com; worker-src data: blob:;"
4
/>

Alternatively, you can set the CSP in the HTML document response header Content-Security-Policy. Check your initial app HTML document load for the header to make sure you are setting it to the desired value.

Explore supported features

The session replay plugin supports the following features. After the SDK and session replay plugin are initialized, you can access these from within your application.

Record canvas

The session replay plugin can record a snapshot bitmap of an HTMLCanvasElement for WebGL capture. The plugin hooks into your WebGL render function after you paint to the WebGL context.

To set this up, pass the following options when you initialize the plugin:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
6
const client = initialize('client-side-id-123abc', context, {
7
  plugins: [
8
    new SessionReplay({
9
      enableCanvasRecording: true, // enable canvas recording
10
      samplingStrategy: {
11
        canvasManualSnapshot: 2, // snapshot at 2 fps
12
        canvasMaxSnapshotDimension: 480, // snapshot at a max 480p resolution
13
      },
14
    })
15
  ]
16
});

Then, hook into your WebGL rendering code and call snapshot:

1
engine.runRenderLoop(() => {
2
  scene.render()
3
  LDRecord.snapshot(canvasElementRef.current)
4
})

To learn more, read snapshot.

Manually control session recording

By default, sessions are automatically recorded after you initialize the session replay plugin. If you want to control recording manually, set manualStart to true in the plugin options:

1
const context = {
2
  kind: 'user',
3
  key: 'context-key-123abc'
4
};
5
6
const client = initialize('client-side-id-123abc', context, {
7
  plugins: [
8
    new SessionReplay({ manualStart: true })
9
  ]
10
});

Then, start session replay yourself:

1
LDRecord.start({
2
  forceNew: true, //start a new recording session
3
  silent: false // if true, console.warn messages created in this method are skipped
4
});

To stop session replay:

1
LDRecord.stop();

To learn more, read start and stop.

Retrieve session URLs on the client

The session replay plugin also provides options for retrieving details about the current recorded session. This can be useful for building a custom integration with the session replay data.

getSession returns details of the current recording session, including a URL to view the session, and a URL for the exact time the method is called, relative to the session recording. For example, suppose an error is thrown in your app and you want to save the session URL to another application. You can use the session details urlWithTimestamp to set the player to the time when the error occurs.

Here’s how:

1
LDRecord.getSession().then(({url, urlWithTimestamp}) => {
2
  console.log(url, urlWithTimestamp);
3
});

To learn more, read getSession.

To determine whether the current session is recording, use getRecordingState:

1
// returns 'NotRecording' or 'Recording'
2
const recordingState = LDRecord.getRecordingState();

To learn more, read getRecordingState.

Review session replays in LaunchDarkly

After you initialize the SDK and session replay plugin, your application automatically starts sending session replay data back to LaunchDarkly. You can review this information in the LaunchDarkly user interface. To learn how, read Observability and Session replay.

When the session replay plugin send replay data back to LaunchDarkly, it automatically injects several attributes, to provide additional help with searching for sessions in the LaunchDarkly user interface. To learn more, read Search.