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.

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.

You’ll need the following identifiers:

• Your LaunchDarkly environment’s client-side ID. To learn more, read Initialize the client in the JavaScript SDK reference guide.
• Your observability project ID. To find your observability project ID, navigate to any of the “Monitor” pages (Sessions, Errors, Logs, Traces) in the LaunchDarkly user interface.
  • If you have not set up sessions yet, click Observability Project ID in the installation guide to copy your observability project ID.
  • Otherwise, click the question mark icon in the lower right. Choose Copy Observability Project ID.

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: [
8
    // replace OBSERVABILITY_PROJECT_ID with your observability project ID,
9
    // which is available on the Sessions page in the LaunchDarkly UI
10
    new SessionReplay(OBSERVABILITY_PROJECT_ID)
11
  ]
12
});

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
// replace OBSERVABILITY_PROJECT_ID with your observability project ID,
4
// which is available on the Sessions page in the LaunchDarkly UI
5
LDRecord.init(OBSERVABILITY_PROJECT_ID);

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(OBSERVABILITY_PROJECT_ID, {
9
      networkRecording: {
10
        enabled: true,
11
        recordHeadersAndBody: true,
12
      },
13
      privacySetting: 'none',
14
    })
15
  ]
16
});

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

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(OBSERVABILITY_PROJECT_ID, {
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(OBSERVABILITY_PROJECT_ID, {
9
      manualStart: true
10
    })
11
  ]
12
});

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.