This article covers how to install Session Replay using the [React Native SDK](/docs/sdks/analytics/react-native/react-native-sdk) plugin. If your application uses the React Native SDK, use this option.
## Quickstart
{% code-group %}
```bash npm
npm install @amplitude/plugin-session-replay-react-native --save
```
```bash yarn
yarn add @amplitude/plugin-session-replay-react-native
```
{% /code-group %}
Configure your application code.
```js
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
| Name | Type | Required | Default | Description |
| -------------------- | ----------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sampleRate` | `number` | No | `0` | Controls how many sessions Session Replay selects for replay collection. The number is a decimal between 0 and 1, for example `0.4`, representing the fraction of sessions Amplitude randomly selects for replay collection. Over a large number of sessions, `0.4` selects `40%` of those sessions. This field isn't required because Session Replay supports [Remote Configuration](/docs/admin/account-management/account-settings#session-replay-settings) of settings including Sample Rate. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](/docs/admin/account-management/account-settings#session-replay-settings). |
| `logLevel` | `LogLevel` | No | `LogLevel.Warn` | Sets the log level for the Session Replay plugin. |
| `autoStart` | `boolean` | No | `true` | Controls whether Session Replay starts automatically when initialized. If set to `false`, manually call the `start()` method to begin capture. |
| `maskLevel` | `MaskLevel` | No | `Medium` | Level of masking applied to sensitive content. Options: `Light`, `Medium`, `Conservative`. Configure this setting to control automatic masking behavior, or use remote configuration through the Session Replay settings page. |
### 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.
```js
import { AmpMaskView } from "@amplitude/plugin-session-replay-react-native";
// ...
{title}
;
```
To unmask a view later, change the mask property to `amp-unmask`.
```js
import { AmpMaskView } from "@amplitude/plugin-session-replay-react-native";
// ...
{title}
;
```
### User opt-out
The Session Replay plugin follows the [React Native SDK's `optOut` setting](/docs/sdks/analytics/react-native/react-native-sdk#opt-users-out-of-tracking), 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.
```js
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`:
```js
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:
```js
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](/docs/admin/account-management/account-settings#session-replay-settings), or use the `sampleRate` configuration option to set the percentage of total sessions that Session Replay captures. For example:
```js
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](/docs/session-replay).
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](/docs/admin/account-management/account-settings#session-replay-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:
```text
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}}
```js
```
{{/noparse}}
{% partial file="session-replay/sr-retention.md" /%}
### DSAR API
The Amplitude [DSAR API](/docs/apis/analytics/ccpa-dsar) 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.
```json
{
"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](/docs/apis/analytics/user-privacy/) 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](/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.