Configuration for session replay

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.

Privacy

When you configure the plugin options, you can choose from the following privacy settings:

• set privacySetting to default to obfuscate all inputs and any text that matches commonly used regex expressions for personally identifiable information (PII).
• set privacySetting to strict to obfuscate all HTML DOM text and images.
• set privacySetting to none if you don’t want to obfuscate anything.

By default, strict privacy mode is enabled. This provides the safest option as no PII should be captured, but it may limit session replay usability.

With default privacy mode, the plugin obfuscates all inputs and any text that matches commonly used regex expressions for personally identifiable information (PII). This functionality offers a base level protection from recording info such as addresses, phone numbers, social security numbers, and more. It does not obfuscate any images or media content. It may obfuscate other, non-PII text if that text matches the expressions that the plugin is using.

Email: '[a-zA-Z0-9.!#$%&'*+=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:.[a-zA-Z0-9-]+)*'
SSN: '[0-9]{3}-?[0-9]{2}-?[0-9]{4}'
Phone number: '[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}'
Credit card: '[0-9]{4}-?[0-9]{4}-?[0-9]{4}-?[0-9]{4}'
Unformatted SSN, phone number, credit card: '[0-9]{9,16}'
Address: '[0-9]{1,5}.?[0-9]{0,3}\s[a-zA-Z]{2,30}\s[a-zA-Z]{2,15}'
IP address: '(?:[0-9]{1,3}.){3}[0-9]{1,3}'

If you need additional customization, you can define a function to edit or remove data in request/response pairs, and add include the function in the networkRecording.requestResponseSanitizer option in the plugin. To learn more, read RequestResponsePair and HighlightOptions.

In addition to setting the privacySetting for the plugins, you can also make adjustments at the HTML element level:

• Add class="highlight-block" to elements that should be ignored. When the session recording is replayed, an empty placeholder replaces the content.
• Add class="highlight-mask" to obfuscate specific HTML elements.
• Add class="highlight-ignore" to input elements to preserve the styling of the input element, but ignore all end user input. This class is only available for <input> elements.
• When privacySetting is default, you can override obfuscation on a per HTML element basis by adding the data-hl-record="true" attribute to the recorded HTML tag.

Record canvas

The session replay plugin can record a snapshot bitmap of an HTMLCanvasElement for WebGL capture.

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.

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.

Canvas and WebGL

When you configure the plugin options for the session replay plugin, you can set up recording of <canvas> elements. This includes <canvas> elements that use WebGL.

Here’s how:

1
const options = {
2
  plugins: [
3
    new SessionReplay({
4
      enableCanvasRecording: true, // enable canvas recording
5
      samplingStrategy: {
6
        canvasManualSnapshot: 2, // snapshot at 2 fps
7
        canvasMaxSnapshotDimension: 480, // snapshot at a max 480p resolution
8
      },
9
    })
10
  ]
11
};

The samplingStrategy options include the following:

• samplingStrategy.canvas is the frame per second rate used to record the HTML canvas. We recommend using a value of less than 5 to ensure the recording is not too large and does not have issues with playback.
• samplingStrategy.canvasManualSnapshot is the frame per second rate used in manual snapshotting mode.
• samplingStrategy.canvasFactor is the resolution scaling factor applied to both dimensions of the canvas.
• samplingStrategy.canvasMaxSnapshotDimension is the maximum recording resolution of the largest dimension of the canvas.
• samplingStrategy.canvasClearWebGLBuffer disables WebGL buffer clearing when set to false. This may help if the canvas flickers when recording.
• samplingStrategy.canvasInitialSnapshotDelay is the time in milliseconds to wait before the initial snapshot of canvas/video elements.

Working with iframes

You can record <canvas> elements within an <iframe>. However, you should be aware of the following caveats:

• The iframe will not load if the source’s origin has a restrictive X-Frame-Options header.
• If the iframe source becomes invalid after some time, or does not render content when inserted into a different domain, the session recording will not show the content that the end user saw.

By default, LaunchDarkly only supports recording same-origin iframes. If you can initialize the SDK and observability plugin within the iframe, you can record the events as a separate session.

In some cases, you may need to record a cross-origin iframe. These are <iframe> elements in your application that reference a domain considered to be part of a different origin. When your iframe uses a src tag pointing to a different origin, the iframe is not accessible from the parent page. However, the iframe can still emit messages that the parent page can hear.

To support cross-origin iframes, set the recordCrossOriginIframe option to true when you initialize the SDK in both the parent window and the iframe.

Here’s how:

1
const options = {
2
  plugins: [
3
    new SessionReplay({
4
      recordCrossOriginIframe: true
5
    })
6
  ]
7
};

If your application is deployed into a cross-origin iframe of a parent application that you do not control, set the recordCrossOriginIframe option to false. This starts the recording for the iframe in standalone mode, and records a session with just the contents of the iframe.

To learn more, read recordCrossOriginIframe in HighlightOptions.

Using a proxy

If your sessions are not appearing in LaunchDarkly, it may be that requests to LaunchDarkly are being blocked. This may be happening for any of several reasons, including third-party browser extensions, browser configuration, or VPN settings.

If you have access to your domain’s DNS settings, you can set up a proxy from your domain to LaunchDarkly to avoid having requests blocked.

Here’s how:

1. On your domain, add two CNAME records:

   • A CNAME record that points pub.ld.<your_domain> to pub.observability.app.launchdarkly.com.
   • A CNAME record that points otel.ld.<your_domain> to otel.observability.app.launchdarkly.com. This record is optional if you are only using the session replay plugin, but required if you are also using the observability plugin.

   Together, these records mean that if you have an app running at <your_domain>, your DNS records will point pub.ld.<your_domain> and otel.ld.<your_domain> to the LaunchDarkly servers.

2. In your application, set the backendUrl option when you configure the observability plugin. Set the backendUrl option to pub.ld.<your_domain>.

   Here’s how:

   Plugin options

   1
   // the examples assume your_domain is acme.com
   2
   3
   const options = {
   4
     plugins: [
   5
       new SessionReplay({
   6
         backendUrl: 'https://pub.ld.acme.com',
   7
       })
   8
     ]
   9
   };

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.

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

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

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.

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.

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

1
// main.js
2
3
const app = createApp(App)
4
app.use(LDPlugin, {
5
  clientSideID: 'client-side-id-123abc',
6
  options: {
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
})
17
app.mount(#app)

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
// main.js
2
3
const app = createApp(App)
4
app.use(LDPlugin, {
5
  clientSideID: 'client-side-id-123abc',
6
  options: {
7
    plugins: [
8
      new SessionReplay({ manualStart: true })
9
    ]
10
  }
11
})
12
app.mount(#app)

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.