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.

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. As usual, you’ll need your LaunchDarkly environment’s client-side ID for this. To learn more, read Initialize the client in the JavaScript SDK reference guide.

You will also need your observability project ID. To request your observability project ID, start a Support ticket or contact your LaunchDarkly account representative.

Here’s how:

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
  ]
10
});

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/observability";
2
3
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.

Record sessions

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.

Get session information

The session replay plugin also provides options for retrieving information about the recorded sessions.

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();

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 replays.