@amplitude/session-replay-browser v1.3.1

@amplitude/session-replay-browser

Official Session Replay SDK

Installation

This package is published on NPM registry and is available to be installed using npm and yarn.

# npm
npm install @amplitude/session-replay-browser

# yarn
yarn add @amplitude/session-replay-browser

Usage

This SDK provides access to the Amplitude Session Replay product.

This plugin requires that default tracking for sessions is enabled. If default tracking for sessions is not enabled in the config, the plugin will automatically enable it.

1. Import Amplitude packages

• @amplitude/session-replay-browser

import * as sessionReplay from '@amplitude/session-replay-browser';

2. Initialize session replay collection

The SDK must be configured via the following code. This call kicks off collection of replays for the user.

sessionReplay.init(API_KEY, {
  deviceId: DEVICE_ID,
  sessionId: SESSION_ID,
  sampleRate: 0.5,
});

3. Get session replay event properties

Any event that occurs within the span of a session replay must be tagged with properties that signal to Amplitude to include it in the scope of the replay. The following shows an example of how to use the properties

const sessionReplayProperties = sessionReplay.getSessionReplayProperties();
track(EVENT_NAME, {
  ...eventProperties,
  ...sessionReplayProperties
})

4. Update session id

Any time that the session id for the user changes, the session replay SDK must be notified of that change. Update the session id via the following method:

sessionReplay.setSessionId(UNIX_TIMESTAMP)

You can optionally pass a new device id as a second argument as well:

sessionReplay.setSessionId(UNIX_TIMESTAMP, deviceId)

5. Shutdown (optional)

If at any point you would like to discontinue collection of session replays, for example in a part of your application where you would not like sessions to be collected, you can use the following method to stop collection and remove collection event listeners.

sessionReplay.shutdown()

Options

Privacy

By default, the session replay will mask all inputs, meaning the text in inputs will appear in a session replay as asterisks: ***. You may require more specific masking controls based on your use case, so we offer the following controls:

1. Unmask inputs

In your application code, add the class .amp-unmask to any input whose text you'd like to have unmasked in the replay. In the session replay, it will be possible to read the exact text entered into an input with this class, the text will not be converted to asterisks.

2. Mask non-input elements

In your application code, add the class .amp-mask to any non-input element whose text you'd like to have masked from the replay. The text in the element, as well as it's children, will all be converted to asterisks.

3. Block non-text elements

In your application code, add the class .amp-block to any element you would like to have blocked from the collection of the replay. The element will appear in the replay as a placeholder with the same dimensions.

4. Block elements by CSS selectors.

In the SDK initialization code, you can configure the SDK to block elements based on CSS selectors.

sessionReplay.init(AMPLITUDE_API_KEY, {
  sampleRate: 0.01, 
  privacyConfig: {
      blockSelector: ['.ignoreClass', '#ignoreId']
  }
})