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 React Native SDK, use this option.

Before you begin

Use the latest version of the Session Replay React Native plugin above {{sdk_versions:session_replay_react_native_plugin}}. For more information, refer to the change log on GitHub.

Quickstart

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

Configure your application code.

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

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // default 0
    autoStart: true, // default true
};
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>

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>

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.

{{noparse}}

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

{{/noparse}}

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.