Session Replay React Native SDK Plugin

This article covers how to install Session Replay using the React Native SDK plugin. If your application uses the Amplitude React Native SDK, use this option.

If you instrument Session Replay without the Amplitude Analytics SDK, go to the Session Replay React Native Standalone SDK.

Quickstart

npm install @amplitude/plugin-session-replay-react-native --save

Configure your application code.

import { SessionReplayPlugin, MaskLevel } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // default 0
    autoStart: true, // default true
    maskLevel: MaskLevel.Medium, // default Medium
};
await init('YOUR_API_KEY').promise;
await add(new SessionReplayPlugin(config)).promise;

Configuration

Mask onscreen data

Session Replay lets you mask or obfuscate areas of your application that may contain sensitive data or PII. Masking happens at the view level. To mask a view, add the AmpMaskView tag with the amp-mask mask property around the section you're masking.

import { AmpMaskView } from "@amplitude/plugin-session-replay-react-native";

// ...

<AmpMaskView mask="amp-mask">
  <Text
    style={[
      styles.sectionTitle,
      {
        color: isDarkMode ? Colors.white : Colors.black,
      },
    ]}
  >
    {title}
  </Text>
</AmpMaskView>;

AmpMaskView is a regular React Native layout node, so it takes part in layout exactly like a View and doesn't make itself transparent to layout. When you wrap existing content, apply the sizing and flex styles that the content relies on to the AmpMaskView itself, such as flex: 1, an explicit width and height, or alignItems. Without those styles, the wrapper can collapse or resize the region you wrapped.

To unmask a view later, change the mask property to amp-unmask.

import { AmpMaskView } from "@amplitude/plugin-session-replay-react-native";

// ...

<AmpMaskView mask="amp-unmask">
  <Text
    style={[
      styles.sectionTitle,
      {
        color: isDarkMode ? Colors.white : Colors.black,
      },
    ]}
  >
    {title}
  </Text>
</AmpMaskView>;

To replace a view with an empty placeholder of the same dimensions, set the mask property to amp-block.

Platform differences in masking

Android and iOS resolve AmpMaskView with different native Session Replay libraries, so identical markup can behave differently on each platform. Test your masking on both platforms before you release.

Session Replay applies these representations on the device when it captures each frame, so the uploaded replay data holds the masked representation instead of the original text or pixels. The player can't restore masked content later.

To keep a region visible on both platforms, place its amp-unmask wrapper outside every amp-mask and amp-block region rather than nesting it inside one.

User opt-out

The Session Replay plugin follows the React Native SDK's optOut setting, and doesn't support user opt-outs on its own.

Start and stop recording

The Session Replay plugin provides start() and stop() methods to start and stop recording sessions. Call these methods to control the recording of specific pages or features in your application.

import { SessionReplayPlugin } from "@amplitude/plugin-session-replay-react-native";

// ...

await init("YOUR_API_KEY").promise;
const sessionReplayPlugin = new SessionReplayPlugin();
await add(sessionReplayPlugin).promise;

// Stop recording
await sessionReplayPlugin.stop();

// Resume recording
await sessionReplayPlugin.start();

To initialize the plugin without automatically starting capture, set the autoStart configuration option to false:

import { SessionReplayPlugin } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true,
    sampleRate: 1,
    autoStart: false, // Don't start capturing automatically
};
await init('YOUR_API_KEY').promise;
const sessionReplayPlugin = new SessionReplayPlugin(config);
await add(sessionReplayPlugin).promise;

// Later, when you want to begin capture
await sessionReplayPlugin.start();

EU data residency

Session Replay is available to Amplitude customers who use the EU data center. Set the serverZone configuration option to EU during initialization. For example:

import { SessionReplayPlugin } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // default 0
    serverZone: "EU" // [tl! ~~]
};
await init('YOUR_API_KEY').promise;
await add(new SessionReplayPlugin(config)).promise;

Sampling rate

By default, Session Replay captures 0% of sessions for replay. If you enable Remote Configuration, update the sample rate from the Session Replay settings page, or use the sampleRate configuration option to set the percentage of total sessions that Session Replay captures. For example:

import { SessionReplayPlugin } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // [tl! ~~]
};
await init('YOUR_API_KEY').promise;
await add(new SessionReplayPlugin(config)).promise;

To set the sampleRate, consider the monthly quota on your Session Replay plan. For example, if your monthly quota is 2,500,000 sessions and you average 3,000,000 monthly sessions, your quota is 83% of your average sessions. In this case, to ensure sampling lasts through the month, set sampleRate to .83 or lower.

Note the following as you consider your sample rate:

• When you reach your monthly session quota, Amplitude stops capturing sessions for replay.
• Session quotas reset on the first of every month.
• Use sample rate to distribute your session quota across a month, rather than using your full quota at the beginning of the month.
• To find the best sample rate, Amplitude recommends that you start low, for example .01. If this value doesn't capture enough replays, raise the rate over a few days. For ways to monitor the number of session replays captured, refer to View the number of captured sessions.

Session Replay supports remote sampling rate settings. This lets users in your organization configure or update the sampling rate of your project after implementation, without a code change. If there's a conflict, Session Replay defaults to the remote setting. For more information, refer to Account Settings.

Troubleshooting

Android crashes with null pointer exception

If your Android app crashes with a NullPointerException related to the serverZone parameter when using custom server URLs, ensure you're using the latest version of the Session Replay React Native plugin. Earlier versions required you to explicitly set the serverZone parameter when using custom serverUrl configurations.

The error typically appears as:

java.lang.NullPointerException: Parameter specified as non-null is null: method com.amplitude.pluginsessionreplayreactnative.PluginSessionReplayReactNativeModule.setup, parameter serverZone

Solution: Update to the latest version of @amplitude/plugin-session-replay-react-native, where the serverZone parameter is optional and defaults to US if not specified.

Track web views (beta)

By default, Session Replay blocks web views, and doesn't track them. If you want to track web views in your application, wrap the view in the AmpMaskView tag, and apply the amp-unmask mask property.

<AmpMaskView mask="amp-unmask" style={{ flex: 1 }}>
  <WebView source={{ uri: "https://reactnative.dev/" }} style={{ flex: 1 }} />
</AmpMaskView>

Data retention

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests.

Retention period

If your Amplitude plan includes Session Replay, Amplitude retains raw replay data for 30 days from the date of ingestion.

Purchase extra retention time, up to a maximum of 12 months. For more information, contact Amplitude Support.

If you purchase extra session volume, Amplitude retains raw replay data for up to 12 months from the date of ingestion. If you need a more strict policy, contact Amplitude support to set the value to 30 days.

Changes to the retention period impact replays ingested after the change. Sessions captured and ingested before a retention period change retain the previous retention period.

Replays that are outside of the retention period aren't viewable in Amplitude.

DSAR API

The Amplitude DSAR API returns metadata about session replays, but not the raw replay data. Amplitude automatically creates the [Amplitude] Replay Captured event when Session Replay captures a session. This event includes the [Amplitude] Session Replay ID property, which provides information about the sessions collected for replay for the user.

{
 "amplitude_id": 123456789,
 "app": 12345,
 "event_time": "2020-02-15 01:00:00.123456",
 "event_type": "first_event",
 "server_upload_time": "2020-02-18 01:00:00.234567",
 "device_id": "your device id",
 "user_properties": { ... }
 "event_properties": {
 "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
 }
 "session_id": 1699922971244,
}

Data deletion

Session Replay uses Amplitude's User Privacy API to handle deletion requests. Successful deletion requests remove all session replays for the specified user.

When you delete the Amplitude project that uses Session Replay, Amplitude deletes that replay data.

Bot filter

Session Replay uses the same block filter available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.