Session Replay React Native Standalone SDK

This article covers how to install Session Replay using the standalone React Native SDK. Use this option to instrument Session Replay without the Amplitude Analytics SDK.

If your application already uses the Amplitude React Native SDK, use the Session Replay React Native SDK Plugin instead.

Before you begin

Use the latest version of the Session Replay React Native SDK above version 0.0.1-beta.1. For more information, review the change log on GitHub.

Quickstart

npm install @amplitude/session-replay-react-native@0.0.1-beta.1 --save

Configure your application code.

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

const config: SessionReplayConfig = {
    apiKey: 'YOUR_API_KEY',
    deviceId: 'YOUR_DEVICE_ID',
    sessionId: Date.now(),
    sampleRate: 1, // default 0
    enableRemoteConfig: true, // default true
    autoStart: true, // default true
    maskLevel: MaskLevel.Medium, // default Medium
};

await init(config);

Configuration

Pass the configuration on initialization of the Session Replay SDK.

Methods

init

Initialize the Session Replay SDK with your configuration.

import { init, SessionReplayConfig } from '@amplitude/session-replay-react-native';

const config: SessionReplayConfig = {
    apiKey: 'YOUR_API_KEY',
    deviceId: 'YOUR_DEVICE_ID',
    sessionId: Date.now()
};

await init(config);

start

Starts recording session replay. Use this method when you initialize the SDK with autoStart: false, or after a previous call to stop().

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

await start();

stop

Stops recording session replay.

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

await stop();

setSessionId

Updates the session identifier. Call this method whenever the session ID changes so session replay data correlates with your analytics events.

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

await setSessionId(Date.now());

setDeviceId

Updates the device identifier. Call this method whenever the device ID changes so session replay data correlates with your analytics events.

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

await setDeviceId('new-device-id');
// or clear device ID
await setDeviceId(null);

getSessionId

Gets the current session identifier from the Session Replay SDK.

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

const sessionId = await getSessionId();
console.log('Current session ID:', sessionId);

flush

Flushes pending session replay data to the server. Forces immediate upload of recorded session data buffered locally.

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

await flush();

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, wrap the section with the AmpMaskView tag and set the mask property to amp-mask.

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

// ...

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

Unmask views

To unmask a view that would otherwise be masked by the global mask level, change the mask property to amp-unmask.

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

// ...

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

Block views

To block a view from recording entirely, use the amp-block mask property.

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

// ...

<AmpMaskView mask="amp-block">
    <Text>This content will be completely blocked from recording</Text>
</AmpMaskView>

Track web views (beta)

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

import { AmpMaskView } from '@amplitude/session-replay-react-native';
import { WebView } from 'react-native-webview';

// ...

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

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.

import { init, SessionReplayConfig } from '@amplitude/session-replay-react-native';

const config: SessionReplayConfig = {
    apiKey: 'YOUR_API_KEY',
    deviceId: 'YOUR_DEVICE_ID',
    sessionId: Date.now(),
    serverZone: 'EU' // Set to EU for data residency
};

await init(config);

Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use the sampleRate configuration option to set the percentage of total sessions Session Replay captures.

import { init, SessionReplayConfig } from '@amplitude/session-replay-react-native';

const config: SessionReplayConfig = {
    apiKey: 'YOUR_API_KEY',
    deviceId: 'YOUR_DEVICE_ID',
    sessionId: Date.now(),
    sampleRate: 0.1 // Capture 10% of sessions
};

await init(config);

When you 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. To make sampling last through the month, set sampleRate to .83 or lower.

Consider the following as you set 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 the month, rather than using your full quota at the beginning.
• 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. Users in your organization can 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.

User opt-out

To opt users out of session replay collection, set the optOut configuration option to true during initialization, or update it dynamically by reinitializing the SDK.

import { init, SessionReplayConfig } from '@amplitude/session-replay-react-native';

const config: SessionReplayConfig = {
    apiKey: 'YOUR_API_KEY',
    deviceId: 'YOUR_DEVICE_ID',
    sessionId: Date.now(),
    optOut: true // Opt out of session replay collection
};

await init(config);