# Amplitude Documentation — Session Replay
# Generated: 2026-09-08T23:40:00Z
# Pages included: 28 of 28
# Source: https://amplitude.com/docs/llms.txt
# Product feed: llms-session-replay.txt
> Session Replay setup, privacy, playback, and platform SDK plugins.
> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.
================================================================================
# Session Replay
URL: https://amplitude.com/docs/session-replay
================================================================================

# Session Replay

Session Replay records the rendered DOM of a user's web or mobile session and plays it back as video, synced with that user's event stream in Amplitude. Open a replay from a chart, the homepage, or User Look-Up to watch what a user clicked, typed, and saw at each event, including console errors, network failures, rage clicks, and dead clicks captured during the session.

Use Session Replay when a chart shows a drop-off or anomaly and you need the qualitative behavior behind it. For pure quantitative breakdowns of where users drop off, use [Funnel Analysis](https://amplitude.com/docs/analytics/charts/funnel-analysis/funnel-analysis-build) or [Journeys](https://amplitude.com/docs/analytics/charts/journeys/journeys-understand-paths) instead.

**Outcome:** [Instrument Session Replay](https://amplitude.com/docs/session-replay/instrument-session-replay)

Pair your metrics with a video of what users actually did.

**Outcome:** [Find the session behind the metric](https://amplitude.com/docs/session-replay/session-replay-viewer)

Go from a chart, funnel, or support ticket to the exact session.

**Outcome:** [See where users click and scroll](https://amplitude.com/docs/heatmaps)

Understand which parts of a page get attention and which get ignored.

**Outcome:** [Spot friction users don't report](https://amplitude.com/docs/session-replay/overview#frustration-analytics)

Catch rage clicks, dead clicks, and errors across sessions.

**Outcome:** [Protect customer privacy](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay)

Mask sensitive content, honor consent, and control what gets captured.

**Outcome:** [Capture the sessions that matter](https://amplitude.com/docs/session-replay/targeted-replay-capture)

Focus replays on specific users, pages, and flows.

## Instrument Session Replay

Session Replay requires instrumentation beyond standard Amplitude instrumentation. Start with the [SDK catalog](https://amplitude.com/docs/session-replay/instrument-session-replay), or jump to the implementation guide for your platform.

- [Browser SDK plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) for teams that already use the Amplitude Browser SDK.
- [Browser standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk) for teams that need replay capture without the Browser SDK.
- [iOS plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin) or [iOS standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk).
- [Android plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin) or [Android standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone).
- [React Native plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin) or [React Native standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk).
- [Google Tag Manager](https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager), [Segment](https://amplitude.com/docs/sdks/session-replay/session-replay-integration-with-segment), and [RudderStack](https://amplitude.com/docs/sdks/session-replay/session-replay-rudderstack-integration) integrations.

## View and analyze replays

Use replays to understand the exact user sessions behind charts, support tickets, and homepage activity. Pair playback with analysis tools that surface patterns across many sessions.

- [View and search replays](https://amplitude.com/docs/session-replay/session-replay-viewer) from charts, User Look-Up, your homepage, or the replay search page.
- [Create heatmaps](https://amplitude.com/docs/heatmaps) to analyze click, selector, and scroll behavior.
- [Use zoning](https://amplitude.com/docs/zoning-insights) to group related page elements for heatmap analysis.
- [Filter replays by sentiment](https://amplitude.com/docs/session-replay/filter-replays-by-sentiment) to focus on feedback signals.
- [Bookmark session replays](https://amplitude.com/docs/session-replay/bookmarkable-session-replays) to keep important sessions beyond the standard retention period.

## Privacy and operations

Session Replay includes privacy controls for masking, user consent, and user-generated content. Configure these controls before you capture production traffic.

- [Manage privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) for masking levels and overrides.
- [Apply consent management best practices](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) before you capture replay data.
- [Create user-generated content filter rules](https://amplitude.com/docs/session-replay/ugc-filter-rules) to prevent sensitive content capture.
- [Monitor replay ingestion](https://amplitude.com/docs/session-replay/ingestion-monitor) to track capture volume and ingestion health.
- [Configure targeted replay capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) to capture sessions that match specific events, properties, or page URLs.

### [Contextualize User Experience with Session Replay](https://academy.amplitude.com/contextualize-user-experience-with-session-replay)

Learn new tools and strategies for governing and maintaining your Amplitude data for continued business value.

================================================================================
# Session Replay Browser SDK Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-plugin
Updated: 2024-09-19
================================================================================

# Session Replay Browser SDK Plugin

- **Package:** `@amplitude/plugin-session-replay-browser` ([npm](https://www.npmjs.com/package/@amplitude/plugin-session-replay-browser))
- **Latest version:** 1.35.0

> **Note:** Session Replay instrumentation
>
> Session Replay isn't on by default, and requires setup beyond the standard Amplitude instrumentation.

The Session Replay Browser SDK plugin adds session recording to a site already instrumented with Amplitude Browser SDK 2. If your site already uses Amplitude instrumentation, use this option. If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk). For more information about the Browser SDK, go to [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2).

> **Info:** Session Replay and performance
>
> Session Replay minimizes impact on the performance of the web pages where you install it by:
>
> - Processing content asynchronously through webhooks for efficient compression and optimized bundle sizes.
> - Batching requests and using lightweight compression to reduce network connections and bandwidth.
> - Optimizing DOM processing.

### Bundle size

The Session Replay plugin adds to your application's bundle size.

For current bundle size information, check the [npm package page](https://www.npmjs.com/package/@amplitude/plugin-session-replay-browser) or [BundlePhobia](https://bundlephobia.com/package/@amplitude/plugin-session-replay-browser).

### Runtime performance

Session Replay runs asynchronously and processes replay data in the background to avoid blocking the main thread. Performance characteristics include:

- **DOM capture**: DOM snapshot capture typically adds less than 5ms of processing time for each page interaction. Initial page load snapshot capture may take 10-50ms depending on page complexity.
- **Memory usage**: Session Replay stores replay events in memory or IndexedDB (configurable using `storeType`). Memory usage scales with session length and page complexity, typically ranging from 1-10 MB for each active session.
- **CPU impact**: With default settings, Session Replay uses less than 2% of CPU time during normal operation. Session Replay defers compression operations to browser idle periods when `performanceConfig.enabled` is `true` (default).
- **Network bandwidth**: Session Replay compresses replay data before upload, typically reducing payload size by 60-80%. Session Replay batches network requests and sends them asynchronously.

### Performance optimization

To optimize Session Replay performance:

- Enable `useWebWorker`, which moves compression off the main thread and reduces CPU impact.
- Configure `performanceConfig.timeout` to control when deferred compression occurs.
- Set `storeType` to `memory` if you don't need persistence across page reloads, which reduces IndexedDB overhead.

For detailed performance testing results, go to the [Session Replay performance testing blog post](https://amplitude.com/blog/session-replay-performance-testing).

Session Replay captures changes to a page's Document Object Model (DOM), including elements in the shadow DOM. Session Replay then replays these changes to build a video-like replay. For example, at the start of a session, Session Replay captures a full snapshot of the page's DOM. As the user interacts with the page, Session Replay captures each change to the DOM as a diff. When you watch the replay of a session, Session Replay applies each diff back to the original DOM in sequential order to construct the replay. Session replays have no maximum length.

## Before you begin

The Session Replay Plugin requires that:

1. Your application is web-based.
2. You can provide a device ID to the SDK.
3. Your site uses the Browser 2.0 SDK.

### Supported browsers

Session Replay supports the same set of browsers as Amplitude's SDKs. For more information, refer to [Browser Compatibility](https://amplitude.com/docs/get-started/browser-compatibility).

Session Replay may not support all browser extensions or DOM elements that browser extensions introduce.

Session Replay supports Shadow DOM, but exceptions may exist depending on the frameworks your site uses.

## Quickstart

Install the plugin with npm or yarn.

> **Info:** Unified SDK
>
> If you haven't installed the Browser SDK yet, consider using the [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk) instead. The Unified SDK provides a single entry point for all Amplitude features (Analytics, Session Replay, Experiment) and simplifies integration by handling initialization and configuration of all components.

#### npm

```bash
# If you already have Browser SDK installed, install the Session Replay Plugin
npm install @amplitude/plugin-session-replay-browser --save

# OR if you haven't installed Browser SDK yet, use the Unified SDK instead
npm install @amplitude/unified
```

#### yarn

```bash
# If you already have Browser SDK installed, install the Session Replay Plugin
yarn add @amplitude/plugin-session-replay-browser

# OR if you haven't installed Browser SDK yet, use the Unified SDK instead
yarn add @amplitude/unified
```

Configure your application code.

#### Plugin configuration

```js
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";

// Create and Install Session Replay Plugin
const sessionReplayTracking = sessionReplayPlugin();
amplitude.add(sessionReplayTracking);

// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);
```

#### Unified SDK

```js
import { initAll } from "@amplitude/unified";

// Initialize Unified SDK with Session Replay configuration
initAll("YOUR_API_KEY", {
  sessionReplay: {
    sampleRate: "<number>",
  },
});
```

You can also add the code directly to the `<head>` of your site. With this method, make sure your application doesn't initialize the Browser SDK elsewhere. If you initialize the Browser SDK more than one time, you may experience mismatches in Device ID or Session ID.

```html
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.45.8-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.35.0-min.js.gz"></script>
<script>
  const sessionReplayTracking = window.sessionReplay.plugin();
  window.amplitude.add(sessionReplayTracking);
  window.amplitude.init(API_KEY);
</script>
```

> **Info:**
>
> Session Replay instrumentation happens in the context of an Amplitude Project. Amplitude defines your replay quota at the Organization level. As a result, you can have multiple Session Replay implementations across multiple projects, each with its own sample rate, that pull from the same quota.

> **Tip:** Compatibility with Google Tag Manager
>
> The Session Replay plugin scripts load asynchronously when you add them to the `<head>` tag of your page. As a result, this implementation isn't compatible with Google Tag Manager. For more information, go to [Session Replay Implementation with Google Tag Manager](https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager).

## Configuration

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `number` | No | `0` | Controls how many sessions to select 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](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings) of settings including Sample Rate. |
| `privacyConfig` | `object` | No | `undefined` | Supports advanced masking configurations with CSS selectors. |
| `applyBackgroundColorToBlockedElements` | `boolean` | No | `false` | If true, applies a background color to blocked elements for visual masking. This helps you see which elements Session Replay blocks from capture. |
| `debugMode` | `boolean` | No | `false` | Adds an additional debug event property to help debug instrumentation issues (such as mismatching apps). Recommended only for debugging initial setup, not for production. |
| `serverZone` | `string` | No | `US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects in the EU data center. |
| `configServerUrl` | `string` | No | `undefined` | The endpoint URL to fetch remote configuration. If provided, it overrides the default server zone configuration. |
| `trackServerUrl` | `string` | No | `undefined` | The endpoint URL to send session replay data. If provided, Amplitude forwards requests from the SDK there instead of to the default Session Replay endpoint. |
| `shouldInlineStylesheet` | `boolean` | No | `true` | If true, Session Replay stores the contents of inlined stylesheets. During replay, Session Replay uses the stored stylesheet instead of fetching it remotely. This prevents replays from appearing broken due to missing stylesheets. Inlining stylesheets may not work in all cases. If undefined, Session Replay inlines stylesheets. |
| `storeType` | `string` | No | `idb` | How Session Replay stores replay events. `idb` uses IndexedDB to persist replay events when Session Replay can't send all events during capture. `memory` stores replay events only in memory, so events are lost when the page closes. If IndexedDB is unavailable, the system falls back to memory. |
| `performanceConfig.enabled` | `boolean` | No | `true` | If enabled, Session Replay defers event compression to occur during the browser's idle periods. |
| `performanceConfig.timeout` | `number` | No | `undefined` | Optional timeout in milliseconds for the requestIdleCallback API. If specified, this value sets a maximum time for the browser to wait before running the deferred compression task, even if the browser isn't idle. |
| `useWebWorker` | `boolean` | No | `false` | Uses a web worker to compress replay events. This improves performance by moving compression off the main thread. |

### API endpoints

Session Replay uses the following API endpoints:

- **Data ingestion**:

  - US: `https://api-sr.amplitude.com/sessions/v2/track`.
  - EU: `https://api-sr.eu.amplitude.com/sessions/v2/track`.
  - Session Replay sends captured replay data to these endpoints.
- **Remote configuration**:

  - US: `https://sr-client-cfg.amplitude.com/config`.
  - EU: `https://sr-client-cfg.eu.amplitude.com/config`.
  - Session Replay fetches remote configuration from these endpoints.

If you set up a domain proxy, forward requests to these endpoints. You can override these defaults using the `trackServerUrl` and `configServerUrl` configuration options.

### Track default session events

Session Replay enables session tracking by default. This ensures Session Replay captures Session Start and Session End events. If you didn't capture these events before you implement Session Replay, expect an increase in event volume. For more information about session tracking, go to [Browser SDK 2.0 | Tracking Sessions](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-sessions).

#### SDK configuration

Use the Browser SDK configuration to implicitly enable session tracking.

```js
amplitude.init(API_KEY, USER, {
  autocapture: {
    sessions: true,
  },
});
```

#### Plugin configuration

Disable all default tracking by the Browser SDK. In this case, the plugin enables default session tracking.

```js
amplitude.init(API_KEY, USER, {
  autocapture: false,
});
```

> **Info:** Session Start and Session End events
>
> Starting with plugin version 1.12.1, Session Replay no longer captures `Session Start` and `Session End` events by default. To enable capture of these events, set `forceSessionTracking: true`:
>
> ```js
> const sessionReplayTracking = window.sessionReplay.plugin({
>   forceSessionTracking: true, // Enable capture of Session Start and Session End events
>   sampleRate: 1, // 100% sample rate, should reduce for production traffic.
> });
> ```
>
> Amplitude requires at least one event in any captured session to enable playback of the replay.

### Mask on-screen data

The Session Replay SDK offers three ways to mask user input, text, and other HTML elements.

| Element | Description |
| --- | --- |
| `<input>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the class `.amp-unmask`. For example: `<input class="amp-unmask">`. |
| text | To mask text within non-input elements, add the class `.amp-mask`. For example, `<p class="amp-mask">Text</p>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the class `.amp-block`. For example, `<div class="amp-block"></div>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |

Session Replay supports setting a masking level on the [Session Replay Settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) screen in Amplitude. This includes Light, Medium, and Conservative settings.

Session Replay settings also enable remote masking overrides. These enable users in your organization to configure or update masking after implementation.

In the event of a conflict, Session Replay defers to the remote setting. For example:

|  | .selector-1 | .selector-2 | .selector-3 |
| --- | --- | --- | --- |
| Local setting | `mask` | -- | `mask` |
| Remote setting | `unmask` | `unmask` | -- |
| Result | `unmask` | `unmask` | `mask` |

In this example, `.selector-1` has a local setting and a remote setting. The result follows the remote setting, and overrides the setting in the SDK or plugin implementation.

Specify elements to block or mask in the `privacyConfig` object during configuration.

```js
// This configuration blocks .no-track and #ads, sets the default mask level,
// and defines the mask and unmask selectors.
await sessionReplay.init(AMPLITUDE_API_KEY, {
  privacyConfig: {
    blockSelector: ['.no-track', '#ads'],
    defaultMaskLevel: 'medium',
    maskSelector: ['.sensitive-data', '.user-email'],
    unmaskSelector: ['.public-info', '#main-content']
  }
}).promise;
```

#### CSS selectors

Session Replay's configuration supports many types of [CSS Selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors). Specify an element tag (`h1` or `textarea`), a class name (`.hidden`) or a data attribute.

Data attributes may be useful if your class names change often due to hashing. To use  data attributes, add a custom attribute like `data-amp-unmask` or `data-amp-mask` to any HTML element. For example, `<textarea data-amp-unmask></textarea>`, then enclose the attribute in square brackets when you specify the selector, `[data-amp-unmask]`.

> **Note:** Remote configuration
>
> If remote configuration is enabled, and fails to load, Session Replay doesn't capture any sessions. This ensures that Amplitude respects any privacy settings you define in the Admin interface, and you don't accidentally capture sensitive data.

### User opt-out

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

### Content Security Policy (CSP)

If your web application uses a strict Content Security Policy, add the following directives.

#### Required CSP directives

```text
script-src: https://cdn.amplitude.com;
connect-src: https://api-secure.amplitude.com;
worker-src: blob:;
```

#### CSP directives reference

| Directive | Domain | Required | Description |
| --- | --- | --- | --- |
| `script-src` | `https://cdn.amplitude.com` | Yes, if using CDN | Allows the Session Replay plugin and Browser SDK to load from Amplitude's CDN. |
| `connect-src` | `https://api-secure.amplitude.com` | Yes (US) | Allows the SDK to send replay data to Amplitude's US servers. |
| `connect-src` | `https://api.eu.amplitude.com` | Yes (EU) | Allows the SDK to send replay data to Amplitude's EU servers. Required if you set `serverZone: "EU"`. |
| `worker-src` | `blob:` | Yes, if using web workers | Required if you enable the `useWebWorker` option for replay event compression. |

#### API endpoints

Session Replay sends data to the following endpoints:

| Region | Endpoint | Purpose |
| --- | --- | --- |
| US (default) | `https://api-secure.amplitude.com/sessions/track` | Replay data ingestion. |
| EU | `https://api.eu.amplitude.com/sessions/track` | Replay data ingestion for EU data residency. |
| US (default) | `https://api-secure.amplitude.com/sessions/config` | Remote configuration (sample rate settings). |
| EU | `https://api.eu.amplitude.com/sessions/config` | Remote configuration for EU data residency. |

#### Example CSP header

For the US region:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-secure.amplitude.com; worker-src 'self' blob:;
```

For EU data center:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api.eu.amplitude.com; worker-src 'self' blob:;
```

> **Tip:**
>
> If you use the `configServerUrl` or `trackServerUrl` configuration options to specify custom endpoints, add those domains to your `connect-src` directive instead.

### 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
// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
  serverZone: "EU", // [tl! ~~]
}).promise;
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. If you used Amplitude's new account snippet to instrument, sample rate defaults to `1` (100% of sessions) for easier testing. Update the sample rate from the [Session Replay settings page](https://amplitude.com/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
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
  sampleRate: 0.01,
}).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 make sampling last 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 over the course of 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](https://amplitude.com/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 a conflict occurs, Session Replay defaults to the remote setting. For more information, refer to [Account Settings](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings).

### Disable replay collection

After you enable Session Replay, it runs on your site until either:

- The user leaves your site.
- You call `amplitude.remove(sessionReplayTracking.name)`.

> **Note:**
>
> These examples assume you use the variable `sessionReplayTracking` in your initialization code.

Call `amplitude.remove('sessionReplayTracking')` before a user navigates to a restricted area of your site to disable replay collection while the user is in that area.

To restart replay collection, call `amplitude.add(sessionReplayTracking)` to re-add the plugin.

> **Note:**
>
> `amplitude.add()` takes an object of type `Plugin` as a parameter, and `amplitude.remove()` takes a string as a parameter, which is the name of the plugin you want to remove.

> **Note:**
>
> Always wait for `amplitude.add()` to finish before you call `amplitude.remove()`. If you don't, you may get an error in the console: `TypeError: Cannot read properties of undefined (reading 'teardown')`. Use the `promise` property to do this, as shown in either of these examples:
>
> ```js
> await amplitude.add(sessionReplayTracking).promise;
> await amplitude.remove(sessionReplayTracking.name).promise;
> ```
>
> ```js
> const addPromise = amplitude.add(sessionReplayTracking).promise;
> addPromise.then(() => {
>   amplitude.remove(sessionReplayTracking.name).promise;
> });
> ```

You can also use a feature flag product like Amplitude Experiment to create logic that enables or disables replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, and add it to your initialization logic:

```js
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";

// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  const sessionReplayTracking = sessionReplayPlugin({
    sampleRate: 0.5,
  });
  amplitude.add(sessionReplayTracking);
}
```

## Data retention

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

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### 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](https://support.amplitude.com).

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 creates the \[Amplitude\] Replay Captured event automatically when Session Replay captures a replay. This event includes the \[Amplitude\] Session Replay ID property, which provides information about the replays collected for the user.

The session replay ID has the format `<deviceId>/<sessionId>`. If you use [custom session definitions](https://amplitude.com/docs/session-replay/session-matching#requirements-for-custom-session-definitions), the custom session ID value can't contain `/` and must use accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) that the Amplitude app provides. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

Session Replay doesn't set cookies on the user's browser. Instead, it relies on a browser storage option called [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) by default. This option enables continuous replay collection during a session in which the user navigates browser tabs or closes and reopens a tab. The SDK cleans up the data it stores in IndexedDB and shouldn't impact the user's disk space.

If the environment doesn't support IndexedDB, Session Replay falls back to an in-memory storage option. In-memory storage is less durable and data is lost  when the user closes their browser window. Set the config option `storeType` to `'memory'` to force in-memory storage.

If a user opts out of all cookies on your site, use the `optOut` configuration option to disable replay collection for that user.

### IndexedDB best practices

To ensure that IndexedDB is initialized and working properly:

- Review CSP headers to ensure they're not overly restrictive. Ensure `default-src` and `script-src` directives allow necessary sources.
- Perform IndexedDB operations within the same origin. Cross-origin restrictions can block IndexedDB operations.
- Confirm that users use a modern browser that supports IndexedDB. Amplitude recommends the latest versions of Chrome, Firefox, Safari, Edge, or Opera.

### Cookies

Session Replay doesn't use cookies directly, and has no impact on cookie size. [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) uses cookies for session management.

## Known limitations

Note the following limitations as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument your marketing site and web application as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on the marketing site and logs in to the web application.
  - Amplitude captures both sessions.
  - The replay for each session is available to view in the host project.
- Session Replay can't capture the following HTML elements:

  - Canvas.
  - WebGL.
  - `object` tags including plugins like Flash, Silverlight, or Java. Session replay supports `object type="image"`.
  - Lottie animations.
  - Cross-origin `<iframe>` elements that don't load the Session Replay SDK with `crossOriginIframes.enabled: true` (for example, third-party embeds like Stripe or Google Maps). To capture first-party cross-origin iframes, go to [Cross-origin iframe recording](https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes).
  - Assets that require authentication, like fonts, CSS, or images.
- Session Replay isn't compatible with ad blocking software.

### Multiple Amplitude instances

Session Replay supports attachment to a single instance of the Amplitude SDK. If your application uses more than one instance, make sure to start Session Replay on the instance that most relates to your project.

```html
<script>
 const sessionReplayTracking = window.sessionReplay.plugin();
  const instance = window.amplitude.createInstance();
  instance.add(sessionReplayTracking);
  instance.init(API_KEY);
<script>
```

## Troubleshooting

For more information about individual statuses and errors, go to the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

### CSS styling doesn't appear in a replay

When Amplitude captures a replay, it doesn't download and store CSS files or other static assets that are part of your application or site. Session Replay stores references to these files and uses those references when it reconstructs the replay. In some situations, the styling in the replay may differ from your application for the following reasons:

- Assets on your site move or change name. This can happen when you deploy a new version of your application.
- Assets on your site are behind access controls that prevent Amplitude from fetching them.

To help resolve CSS loading issues:

- Ensure your domain is publicly accessible. If you work in a local environment, Amplitude may not have access to assets stored on `localhost`.
- Your CDN should keep track of old stylesheets for older replays. If the content of the same stylesheet changes over time, try to append a unique string or hash to the asset URL. For example, `stylesheet.css?93f8b89`.
- Add `app.amplitude.com` or `app.eu.amplitude.com` to the list of domains that your server's CORS configuration permits.
- Make external stylesheets accessible to Session Replay. To ensure Session Replay can capture external stylesheets, add the `crossorigin="anonymous"` attribute to the `<link rel="stylesheet">` elements in your code.

  This instructs the browser to load the CSS without sending credentials, which allows cross-origin access to the stylesheet rules. Without this attribute, browsers like Google Chrome block programmatic access to those rules (for example, attempts to read `stylesheet.cssRules` fail).

  Although your site appears correctly to users, these restrictions can prevent session replay tools from capturing the full styling information, which results in incomplete or broken visual playback.

### Capture sessions contain limited information

Amplitude creates the `[Amplitude] Replay Captured` event automatically when Session Replay captures a session. If you don't see this event in your implementation, replays may not appear correctly in Amplitude's analysis tools like Funnel Analysis, Segmentation, or Journeys charts. You can still find session replays on the Session Replay home page or the user profile page. Contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new) if you don't see this event.

If you use a method other than the Browser SDK to instrument your events, consider using the [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk/).

### Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This happens when a user closes their browser or browser tab and `[Amplitude] End Session` occurs, but the Browser SDK and Session Replay plugin haven't yet processed it. When the user visits that page again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

Session replays may not appear in Amplitude due to:

- Content security policy
- Blocked JavaScript
- No events triggered through the browser SDK in the current session
- Sampling

#### Local development and focus state

The Session Replay SDK and plugin capture only the page that's in focus. When you develop locally with the browser console open, focus states may not work as expected. If you don't see replays in Amplitude, try to enable `debugMode`. In this mode, Session Replay ignores the focus handle and enables extra debugging information.

```js
const sessionReplayTracking = window.sessionReplay.plugin({
 debugMode: true,  
 sampleRate: 1, 
 });
```

#### Content security policy

When you add the Session Replay script to your site, visit a page on which the Session Replay SDK is running, and open your browser's developer tools.

Check for any error messages in the JavaScript console that contain the text `Content Security Policy`. For example, `Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy`.

To resolve this error, update your site's content security policy to allow connection to Amplitude's APIs.

#### Blocked JavaScript

Browser extensions or network security policy may block the Session Replay SDK. Check your browser's developer tools to see if requests fail, and if so, add an exception for the blocked domains.

#### No events triggered through the browser SDK in the current session

Session Replay requires that at least one event in the user's session has the `[Amplitude] Session Replay ID` property. The [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) `Session Start` and `Session End` events include this property by default. If you instrument your events with any SDK other than the Amplitude Browser SDK 2, use the [Session Replay Standalone SDK](https://amplitude.com/docs/session-replay/session-replay-standalone-sdk) and ensure you tag your events with the necessary event properties.

For local testing, you can force a Session Start event to ensure that Session Replay functions.

1. Open your browser's developer tools, and delete any cookie that begins with `AMP_`.
2. Close developer tools and refresh the page.
3. In Amplitude, in the User Lookup Event Stream, you should see a Session Start event that includes the `[Amplitude] Session Replay ID` property. After processing, the Play Session button should appear for that session.

#### Sampling

As mentioned above, the default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information see, [Sampling rate](#sampling-rate).

#### Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the `[Amplitude] Session Replay ID` property, only that one event in the session has it. Reasons why `[Amplitude] Session Replay ID` may not be present in an event include:

If you instrument an event with a source different from the source you connect to Session Replay. For example, your application may send events from a backend source, rather than the Browser SDK.

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may result from one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a user bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If Session Replay doesn't run on all pages a user visits, their session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 30 days, or 90 days if you purchase extra volume).

================================================================================
# Introducing Session Replay
URL: https://amplitude.com/docs/session-replay/overview
================================================================================

# Introducing Session Replay

Session Replay records real user sessions in your product and replays them, so you can watch exactly what a user did alongside the same events and analytics you track in Amplitude. Use it to understand the "why" behind your product metrics and conversion drops: watch where users hesitate, where they drop off in a funnel, and how they move through the flows you measure quantitatively.

Use Session Replay when you want to watch what one user actually did in a single session. If you want an aggregate view of where users click, tap, and scroll across many sessions, use [Heatmaps](https://amplitude.com/docs/heatmaps) instead.

Find Session Replay in the left-hand sidebar in Amplitude Analytics.

[View and modify Session Replay settings in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings).

> **Note:** Enabling Session Replay
>
> Session Replay isn't enabled by default and requires instrumentation beyond the standard Amplitude instrumentation.

## Data retention

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

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### 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](https://support.amplitude.com).

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.

> **Note:**
>
> The [Session Replay Agent](https://amplitude.com/docs/amplitude-ai/session-replay-agent) analyzes session replays at scale to surface friction points, navigation patterns, and engagement insights automatically.

## Use Session Replay to review user activity

You can launch a session replay from a user's event stream, inside a chart, or from your homepage. Replays are generally available for viewing five minutes after a session begins.

When viewing a session replay from your homepage or from a search, the user's event stream syncs with the replay. You can select an event from the stream, and the replay jumps to that point in the session. Event-stream sync isn't available when viewing a replay from a chart.

Session Replay supports user sessions of any length.

> **Note:** AI generated names
>
> Event names with a _sparkle_ icon indicate that Amplitude has generated a name to provide more context around the action a user is taking. These are Autocapture events ingested as `Page Viewed`, `Element Clicked`, and `Element Changed`. Amplitude uses property information to make these events more valuable in the event stream. Click any event to see its ingested name and properties.

## Error analytics and console logs

Session Replay can capture and display technical errors and console logs that occur during user sessions. Error capture helps you understand whether technical issues are impacting user experience and correlate errors with drops in conversion or engagement.

Error Analytics covers the following types of error capture:

- **Console Errors**: JavaScript console logs, warnings, and errors. Console errors display in the console panel within the session replay modal.
- **Network Errors**: Failed network requests and API calls. Network errors display at the bottom of the session replay modal.

### Requirements

Error Analytics features have different SDK requirements:

| Feature | SDK | Minimum Version |
| --- | --- | --- |
| Console Errors | [Session Replay Browser SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk) (`@amplitude/session-replay-browser`) | 1.22.4 |
| Console Errors | [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) (`@amplitude/plugin-session-replay-browser`) | 1.16.6 |
| Network Errors | [Analytics Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) (`@amplitude/analytics-browser`) | 2.24.0 |

When enabled, Session Replay captures:

- **JavaScript console logs**: Console messages, warnings, and errors logged by your application
- **Network errors**: Failed network requests and API calls
- **Runtime errors**: JavaScript errors that occur during the session

### View console logs in a replay

To view console logs and errors in a session replay:

1. Open a session replay from a chart, User Look-Up, or the Session Replay list.
2. Look for the console icon in the replay interface.
3. Click the console icon to expand the console log view.

The console view displays logs, warnings, and errors in chronological order alongside the session timeline. Click any log entry to jump to that moment in the replay.

### Enable or disable console logs

Admins and managers can enable or disable console log capture through organization settings:

1. Navigate to _Settings > Organization Settings_.
2. Go to the _Session Replay & Heatmaps_ section.
3. Toggle the **Console Logs** setting on or off for your projects.

Changes to this setting apply to future session captures only.

### Analyze error events

Error events captured during sessions appear in your event stream and can be analyzed like any other event. You can:

- Use [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) to measure error frequency and trends
- Include error events in [Funnel Analysis](https://amplitude.com/docs/analytics/charts/funnel-analysis/funnel-analysis-build) to review how errors impact conversion
- Filter session replays by error events to focus on problematic sessions

Error analysis helps quantify the business impact of technical issues and prioritize fixes based on data.

## Replay Captured event

Amplitude automatically sends a `[Amplitude] Replay Captured` event when it successfully captures a session replay. This event includes the `[Amplitude] Session Replay ID` property, which links the event to the captured replay.

The event uses the device ID passed to the Session Replay SDK or browser SDK plugin. The session ID is added to the event based on your project's Amplitude session definition. The event doesn't use user ID.

### Use the Replay Captured event

The `[Amplitude] Replay Captured` event appears in your event stream and you can analyze it like any other event. For example, you can:

- Use [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) to measure replay capture rates and trends.
- Filter charts and analyses by the event to focus on sessions with captured replays.

The `[Amplitude] Replay Captured` event indicates that the replay is available for viewing in Amplitude. When you see this event in a user's event stream, you can view the associated session replay.

> **Note:**
>
> Amplitude sends the `[Amplitude] Replay Captured` event automatically. You don't need to instrument this event yourself. This event doesn't count toward your event volume or MTU (Monthly Tracked Users).

> **Note:**
>
> The `[Amplitude] Replay Captured` event may create anonymous users if the device ID can't be associated with an existing user.

> **Note:**
>
> You may see multiple `[Amplitude] Replay Captured` events in a session replay timeline. Multiple events can appear when multiple browser tabs are open with different active sessions. Amplitude only captures replays when device IDs and session IDs match. Because timelines are based on events captured during the replay period, events from different sessions may overlap in the timeline.

## Frustration analytics

Session Replay automatically detects and highlights user frustration signals during playback. Frustration signals help you identify UX problems that may not be obvious in traditional analytics.

> **Note:** Requirements
>
> Frustration Analytics requires [Analytics Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) (`@amplitude/analytics-browser`) version 2.24.0 or later.

### Frustration event types

- **Rage clicks**: When users rapidly click the same element multiple times, usually indicating something isn't working as expected. A rage click often means a button or link appears interactive but doesn't respond.
- **Dead clicks**: When users click on elements that appear clickable but have no functionality, such as non-interactive images styled like buttons or links that lead nowhere.

### View frustration events in replays

Frustration events appear directly in the session timeline and event stream, making them easy to spot:

1. Open a session replay.
2. Look for rage click and dead click indicators in the timeline.
3. Click on a frustration event to jump to that moment in the replay.

Like error events, frustration events can be analyzed using Event Segmentation and Funnel Analysis to understand their impact on user behavior and conversion rates.

### View Session Replay from User Look-Up

To access Session Replay from a user's event stream, use the [User Look-Up](https://amplitude.com/docs/analytics/user-data-lookup) feature. User Look-Up can be helpful if a user has reported a potential bug during their session, or if you want to understand whether a user's experience is representative of a bigger trend.

Find the user with User Look-Up (you need their user ID to do this), then click _Play Session_ next to the session you're looking for in the event stream. The replay appears to the right, where you can review session activity. You can generate a link to share the replay with your team from the view in a User Look-Up event stream. Click _Copy URL_ from the view to copy the link.

### View Session Replay from a chart

To use Session Replay in a chart, follow these steps:

1. Open the Amplitude chart that contains the events you want to look at.
2. Open the [Microscope](https://amplitude.com/docs/analytics/microscope) and click **Watch Session Replays**.
3. Check the **Streams with session replays** box.

The replay modal appears, where you can:

- Browse the available replays that correspond to the specific data point on the chart
- Pause replay
- Skip forward and backwards by 10-second increments
- Speed up and down
- Skip periods of inactivity
- Navigate to the standalone replay page and watch with event sync
- Copy and share the replay's URL

The user's cursor movement displays as a red line, and masked HTML elements appear as a series of asterisks. Session Replay shows the timestamp of the session as it occurred.

#### Availability in Amplitude charts

Session Replay is available in the following Amplitude chart types, with these restrictions around each chart type's available metrics:

> **Note:**
>
> In the Funnel Analysis row, "Conversion" refers to the funnel's **Measured as** setting — not individual users converting. Once a funnel uses the Conversion measure, replays are available for everyone in the funnel, including users who dropped off.

- **Event Segmentation**: Session replay is available for all six measures.
- **Funnel Analysis**: Session Replay is available when the funnel is measured as Conversion (set in the **Measured as** button group). It isn't available for other measures such as Time to Convert. When a funnel is measured as Conversion, you can watch replays for all outcomes at every step — users who converted to the next step and users who dropped off. Click a converted or drop-off data point at any funnel step to open [Microscope](https://amplitude.com/docs/analytics/microscope), then select **Watch Session Replays**. Events appear in chronological order (oldest to newest).
- **Journeys**: Session replay is available on the Pathfinder and Journey Map visualizations.
- **User Sessions**: Session replay is available for all six measures. The User Sessions chart doesn't allow session replays for [custom defined sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions).
- **Experiment charts**: Session replay is available on all Experiment charts.

### View Session Replay from your homepage

With Session Replay, your homepage shows 100 sessions captured over the past seven days. Each session displays its start time, user ID, session length, and country.

> **Note:**
>
> If you can't see the Session Replay widget and have a customized [home page](https://amplitude.com/docs/get-started/amplitude-home-page), reset the home page and then re-add your customizations to make the widget visible.

Click **Play** to see the session view in the modal that appears.

## View the number of captured replays

To see the number of captured replays, create an [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) chart:

1. Select the `[Amplitude] Replay Captured` event.
2. Group by the `[Amplitude] Session Replay ID` event property.
3. In the formula, use `PROPCOUNT(A)` to count distinct session replay IDs.

`PROPCOUNT(A)` returns the number of distinct property values for the property by which the event is grouped. In this example, the formula retrieves the number of different session replay IDs.

To review your Session Replay quota and retention time frame, navigate to the Plans & Billing page for your organization.

## Search for a replay

Session replay gives you two options for searching replays: either by date, or with a filter.

1. Navigate to the Session Replay page to view the complete list of session replays available for viewing.
2. To narrow the list by date, click the calendar icon just above the list and select the starting and ending dates you want to use. You can also use a preset time range: one day, seven days, or 30 days.

Filtered results by date or time frame match the project's timezone.

3. To narrow the list with a filter, click **Add Filter**. You can filter by cohorts, events, event properties, user properties, and session duration. You can also use multiple filters to further narrow your list.

After you make your selection, view replays that took place within the selected time frame, or replays that meet your filter specifications. Your search results generate a unique URL that you can share with your team.

> **Note:**
>
> Note that if you apply a filter to exclude replays with a specific property value, Session Replay search returns results for all replays with a different value for that property, **and** replays with **missing** values for that property.

The list of results shows a maximum of 100 replays.

## Link directly to a replay

You can construct a direct URL to link to a specific session replay. A direct URL is useful for sharing replays programmatically or embedding links in external tools.

Using the following URL structure:

```text
https://app.[eu.]amplitude.com/analytics/<orgUrl>/session-replay/project/<projectId>/search/replay?sessionReplayId=<replayId>
```

Replace the following placeholders:

| Placeholder | Description | How to find it |
| --- | --- | --- |
| `eu.` | Include this subdomain only for EU-based Amplitude accounts. Omit it otherwise. | Check the URL when logged in to Amplitude. EU accounts use `app.eu.amplitude.com`. |
| `<orgUrl>` | Your organization's URL identifier. | Visible in the browser URL when logged in. For example, `https://app.amplitude.com/analytics/myorg/...`. |
| `<projectId>` | The numeric ID of the project that captured the replay. | Navigate to _Settings > Projects_, select the project, and copy the ID from the URL or project details page. |
| `<replayId>` | The session replay ID. | Available as the `[Amplitude] Session Replay ID` event property on `[Amplitude] Replay Captured` events. |

For example:

```text
https://app.amplitude.com/analytics/myorg/session-replay/project/123456/search/replay?sessionReplayId=abc123def456
```

## How session replay querying works

When you search for replays by event in Amplitude, Amplitude finds replays that span those events. Amplitude looks for replays that include the time period when your events occurred.

![Diagram showing how session replay queries match replays to events: a timeline with queried events highlighted in a bounding box, and a matching replay that starts before and ends after the queried events](https://amplitude.com/docs/images/session-replay/replay-query-matching.svg)

### Matching replays to events

Amplitude matches replays to your events by finding replays that:

1. **Match the session ID**: The replay belongs to the same session as your events. Matching the session ID ensures you're viewing the correct replay for that user session.
2. **Start before your events**: The replay begins before the first event you're looking at
3. **End after your events**: The replay continues past the last event you're looking at

These matching criteria ensure the replay captures the full context around the events you're analyzing. For example, if you're looking at events that occurred between 2:00 PM and 2:05 PM in a specific session, Amplitude returns replays that belong to the same session. The replays started before 2:00 PM and ended after 2:05 PM.

## Add a replay to a dashboard or notebook

There are three ways you can add a Session Replay to a dashboard or notebook:

- From the Session Replay page itself (accessible from the homepage and Session Replay search)
- From within [User Look-Up](https://amplitude.com/docs/analytics/user-data-lookup)
- From within an individual chart

## Use cases

With Session Replay, you can:

- **Improve product conversions**: Blend quantitative and qualitative insights and use new information to hypothesize and test new workflows that boost conversions and revenue.
- **Diagnose product issues faster**: Isolate specific user sessions for troubleshooting bugs, getting critical qualitative context that helps teams speed up resolution process.
- **Identify significant UX behaviors**: Go from micro to macro by checking if single user sessions are representative of larger trends and drive changes that benefit more customers.
- **Unlock qualitative insights at scale**: Explore how users are engaging with a newly launched feature and gauge customer behavior at scale without running surveys or interviews.
- **Tie replays to behaviors that matter**: Sync your user stream to meaningful events in your session replay to quickly inspect behaviors and inform decisions faster.
- **Tell stories and innovate faster**: Share links and add replays to notebooks and dashboards to get buy-in across colleagues and act on initiatives faster.

## Limitations

There are some limitations when using Session Replay:

- Session Replay can only be used to segment by users, and isn't available for [account-level reporting](https://amplitude.com/docs/analytics/account-level-reporting).
- If you are in a portfolio view, you can see replays for different users under different projects. However, note that Session Replay doesn't stitch together replays from a single user across multiple projects. If a user begins a session in one project and then continues to a second project, Amplitude Analytics generates separate replays for that user for each project.
- Session Replay doesn't capture these unsupported HTML elements:

  - Canvas
  - WebGL
  - `object` elements: Plugins such as Flash, Java, Silverlight, and so forth, except `object type="image"`
  - Lottie Animations (web and mobile)
  - Cross-origin iframes that don't load the Session Replay SDK with `crossOriginIframes.enabled: true` (for example, third-party embeds). To capture first-party cross-origin iframes, go to [Cross-origin iframe recording](https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes).
  - Assets that require authentication, like fonts, CSS files, and images

## Troubleshoot replay playback

Sometimes, replays may appear missing or otherwise unavailable for playback. The causes of these issues, and steps you can take to mitigate them, depend on the issue.

### Parts of this session weren't captured

If you experience this error, parts of a replay may show as inactive periods because Amplitude doesn't capture any user interaction during that period. Sometimes, the issue impacts the entire replay.

When you see this error in a replay, one of the following may have happened:

- **The user closed the browser**. Amplitude captures and uploads session replays as users use your product. If users leave the app or close their browser before the session replay upload completes, some parts of the replay appear to be missing in Amplitude and unavailable for playback.
- **Network issues**. If the user on your site or app experiences network degradation, their replay may fail to upload. If you notice a pattern, or commonly experience this issue, contact [Amplitude Support](https://gethelp.amplitude.com/hc/en-us).
- **Requests throttled**. During holiday periods, special events, or other peak times, traffic to your site or app may spike resulting in a large volume of session replays. In these instances, Amplitude may throttle uploads to keep system performance.

If you see this error:

- **Check for throttle errors**. Open the [Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor) and check for a spike in `429` throttling errors. If you know a period of high traffic is coming up due to a campaign or other event, contact [Amplitude Support](https://gethelp.amplitude.com/hc/en-us) for a temporary change to the throttle threshold.
- **Leave in-product feedback**. Leave a thumbs-down if the replay you're viewing doesn't meet expectation.
- **Contact Amplitude**. If you see issues in replay collection that you think might relate to missing data, contact [Amplitude Support](https://gethelp.amplitude.com/hc/en-us).

### Replay temporarily unavailable due to ingestion delay

This message appears when you view a replay that Amplitude ingested within the last five minutes. Amplitude takes one or two minutes to make a replay available for playback.

Live replays that are longer than five minutes become available for playback as soon as Amplitude receives enough data to generate the replay. Refresh the page for the most recent replay data.

================================================================================
# Friction Monitor
URL: https://amplitude.com/docs/session-replay/friction-monitor
================================================================================

# Friction Monitor

Friction Monitor finds the user experience problems that hurt your product most, ranks them by impact, and routes each one to the team that owns it. It detects friction signals that Amplitude captures during real user sessions, groups matching signals into distinct issues, and links the session replays where each issue happened. Product managers, UX teams, and engineers use Friction Monitor to move from a flood of individual friction signals to a short, prioritized list of problems worth fixing.

Use Friction Monitor when you want a ranked, cross-session view of which UX problems to prioritize. If you want to inspect friction signals within a single user's session, watch the [session replay](https://amplitude.com/docs/session-replay/overview) directly instead.

> **Note:** Closed beta
>
> Friction Monitor ships as an internal release and closed beta under _Experience Analytics > Friction Monitor_. Only eligible early-access accounts have access. Contact your Amplitude account team to request access.

## How Friction Monitor works

Friction Monitor turns raw friction signals into a ranked list of issues you can act on. It works in a few stages:

- **Detect and fingerprint signals**: Friction Monitor reads Autocapture data to detect friction signals, then fingerprints each one so it can recognize the same problem across many sessions.
- **Group signals into issues**: It groups matching signals into distinct issues, so a single recurring problem shows up as one issue rather than thousands of separate events.
- **Rank by impact**: Amplitude scores each issue's impact and orders the list so the highest-impact issues surface first. Each assessment includes a short description, an impact score, and recommended actions.
- **Link related replays**: Each issue links to the session replays where it occurred, so you can watch the problem happen in context.
- **Label and route**: Amplitude generates a label for each issue and routes it automatically to the relevant team or owner.

## What Friction Monitor detects

In this release, Friction Monitor detects two types of friction signal:

- **Dead clicks**: Clicks on elements that appear interactive but do nothing, such as a non-interactive image styled like a button or a link that leads nowhere.
- **Error clicks**: Clicks that coincide with an error in the session, which often point to a broken or failing interaction.

Amplitude captures these signals through Autocapture, so you don't need to instrument them manually.

## How Amplitude ranks and routes issues

Friction Monitor prioritizes issues by impact and helps you get each one in front of the right people:

- **Impact ranking**: Amplitude ranks issues by their estimated impact so your team can focus on the problems that matter most.
- **AI labels and automatic routing**: Amplitude generates a label for each issue and routes it to the team or owner responsible for that part of the product.
- **Slack notifications**: Friction Monitor sends notifications to Slack so teams learn about new or high-impact issues without checking the dashboard.
- **Linear integration**: You can connect issues to Linear to track fixes in your existing workflow.
- **MCP tools**: Friction Monitor exposes MCP tools so you can query issues by team, owner, and impact from an AI assistant.

## Prerequisites

To use Friction Monitor, your account needs:

- Access to the Friction Monitor closed beta. Eligibility applies.
- Amplitude AI features enabled.
- [Autocapture](https://amplitude.com/docs/session-replay/overview) enabled, with enough event volume for Amplitude to detect and group friction signals.

## Where to find Friction Monitor

Find Friction Monitor in Amplitude under _Experience Analytics > Friction Monitor_. The list view shows your ranked issues, and selecting an issue opens its detail view with the impact assessment and linked replays.

## Coming soon

> **Note:**
>
> Amplitude is expanding Friction Monitor beyond click-based signals. Planned capabilities include a pipeline that analyzes captured replays more broadly, additional friction types, anomaly detection, and revenue and business-impact analysis. These aren't available yet.

## Limitations

> **Note:**
>
> Friction Monitor detects dead clicks and error clicks in this release. It relies on Autocapture data, so it can't detect friction on interactions that Autocapture doesn't capture. Issue detection and grouping depend on having enough event volume.

================================================================================
# Targeted Replay Capture
URL: https://amplitude.com/docs/session-replay/targeted-replay-capture
================================================================================

# Targeted Replay Capture

Targeted Replay Capture (TRC) focuses your Session Replay quota on sessions that match criteria you define, such as events, event properties, user properties, or page URLs, rather than capturing all sessions or relying on random sampling. Use TRC when you need to observe specific behaviors or high-value segments; if you only need broad session coverage, adjust the global sample rate instead.

Configure TRC by adding conditions to the _Sampling_ control in your project's Session Replay settings. Each condition can match events, event properties, user properties, or page URLs, and you can combine conditions with OR logic. The Session Replay SDK fetches targeting configurations from a remote config service and evaluates them at runtime to decide whether to capture a session.

## Key capabilities

TRC defines the criteria that Amplitude uses to decide whether to capture a session, and helps you manage your Session Replay quota more efficiently.

### Custom capture criteria

Define rules that capture replays based on:

- **Specific events**: For example, `Checkout Started`.
- **Event properties**: For example, `plan = Pro`.
- **User properties**: For example, `country = US`.
- **Page URLs**: For example, capture only sessions on `/checkout` or any URL matching a pattern.
- **Combinations**: Combine these criteria with `OR` logic.

### Configuration and quota management

Manage TRC through the [Session Replay settings page](https://amplitude.com/docs/session-replay/session-replay-settings) by adding conditions to the _Sampling_ control. Add, edit, and remove targeting conditions for each project. The UI estimates how much quota each condition uses based on historical traffic. Set different sample rates for different conditions to control which sessions Amplitude captures and how much quota each condition uses.

## Use cases

- Capture replays only for users who encounter errors or drop off at key points.
- Focus on high-value user segments or critical product flows.
- Capture sessions on specific pages or flows, such as checkout or onboarding.
- Reduce noise and cost by avoiding unnecessary replay capture.

## Configure Targeted Replay Capture

TRC requires [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) version `@amplitude/plugin-session-replay-browser@1.22.0` or higher and [permissions to manage Session Replay settings](https://amplitude.com/docs/admin/account-management/user-roles-permissions). URL matching requires plugin version `1.26.2`+ or standalone SDK `@amplitude/session-replay-browser@1.32.2`+. If you haven't installed the plugin, do that first.

Configure TRC per project:

1. Navigate to _Settings > Organizational Settings > Session Replay Settings_. For more information, refer to the [Session Replay settings page](https://amplitude.com/docs/session-replay/session-replay-settings).
2. Select the project you want to configure.
3. In the _Sampling_ section, select **Add Condition** to create a new targeting condition.
4. Define your targeting criteria for the condition.

Add multiple conditions and combine them with OR logic. Each condition can include:

- Event types.
- Event properties.
- User properties.
- Page URLs.

> **Note:**
>
> You must capture and send events, event properties, and user properties to Amplitude during the session for event- and property-based targeting conditions to work. Page URL conditions evaluate the user's current URL directly and don't require a matching event.

## Page URL targeting

Page URL targeting captures replays only when users visit specific pages or URL patterns. This capability is in beta for web Session Replay.

Page URL targeting requires one of the following SDK versions:

- Plugin: `@amplitude/plugin-session-replay-browser@1.26.2` or higher.
- Standalone SDK: `@amplitude/session-replay-browser@1.32.2` or higher.

To add a Page URL condition:

1. In the _Sampling_ section, select **Add Condition** and open the condition editor.
2. Add a **Page URL** condition.
3. Select an operator and enter a URL or pattern.
4. Set the sample rate for the condition and save.

Supported operators:

| Operator | Matches when |
| --- | --- |
| **is** | The current page URL exactly matches the value you enter. |
| **is not** | The current page URL doesn't exactly match the value you enter. |
| **contains** | The current page URL includes the text you enter. |
| **does not contain** | The current page URL doesn't include the text you enter. |
| **glob match** | The current page URL matches a glob pattern. For example, `https://example.com/checkout/*` matches any checkout subpath. |

> **Tip:**
>
> Use Page URL targeting to focus replay capture on high-value flows such as checkout, onboarding, or account settings without capturing every session.

### How Page URL targeting evaluates

The Session Replay SDK evaluates Page URL conditions against the user's current browser URL. On single-page applications, the SDK re-evaluates targeting when the URL changes. If the user navigates to a URL that no longer matches, capture stops for that session.

> **Note:** Capture timing for Page URLs
>
> For Page URL conditions, replay capture begins when the user's URL matches the condition. Replays don't include activity from before the URL match.

## SDK support

TRC requires the Amplitude Browser Analytics SDK with the Session Replay Browser SDK Plugin version `@amplitude/plugin-session-replay-browser@1.22.0` or higher. Integrate both the Amplitude Browser Analytics SDK and the Session Replay Plugin into your setup to use TRC.

URL matching support requires one of the following:

- Plugin: `@amplitude/plugin-session-replay-browser@1.26.2` or higher.
- Standalone SDK: `@amplitude/session-replay-browser@1.32.2` or higher.

> **Warning:** Standalone SDK limitations
>
> The standalone SDK supports Page URL targeting only. Event-, property-, and user-based TRC conditions require the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) with the Amplitude Browser Analytics SDK.

## Evaluation timing

The SDK fetches the targeting configuration at session start. For event-, property-, and user-based conditions, the SDK uses that configuration for the entire session. If a matching event occurs later in the session, the SDK evaluates it against the configuration that was active at session start. Updates to targeting rules apply only to new sessions.

For Page URL conditions, the SDK also re-evaluates when the URL changes during the session, such as during single-page app navigation.

> **Note:** Capture timing
>
> Session replay capture begins only after the targeting condition triggers. TRC has no "lookback" period. Replays don't capture activity before the condition triggers. For event-based conditions, capture starts when the matching event fires. For Page URL conditions, capture starts when the user's URL matches.

================================================================================
# Self-Host Session Replay SDKs
URL: https://amplitude.com/docs/session-replay/session-replay-self-hosting
================================================================================

# Self-Host Session Replay SDKs

Self-hosting lets you serve Amplitude SDK files and route API calls through your own domain instead of `amplitude.com`. The two main reasons to self-host are:

- **Ad blocker bypass**: Many browser extensions and tracking prevention tools block requests to `amplitude.com` domains. Routing through your own domain avoids the block.
- **Data residency / compliance**: Your organization may require that data never leaves your own infrastructure before it reaches Amplitude.

There are two independent parts to self-hosting:

1. **Host the SDK script:** serve the SDK `.js` file from your own CDN or static file server (browser only; npm/bundled installs skip this step).
2. **Proxy API calls:** forward SDK network requests through your own server before they reach Amplitude's ingestion endpoints.

You can implement either or both parts independently.

---

## Part 1: Self-host the SDK script

Self-hosting the SDK script applies to browser-based SDKs loaded through a `<script>` tag. If you install through npm and bundle the SDK yourself, skip to [Part 2: Proxy API calls](#part-2-proxy-api-calls).

### Get the SDK file

**Option A: Download from Amplitude's CDN:**

```bash
# Session Replay Plugin (latest: 1.28.1)
curl -O https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz

# Session Replay Standalone SDK (latest: 1.39.0)
curl -O https://cdn.amplitude.com/libs/session-replay-browser-1.39.0-min.js.gz

# Browser SDK (latest: 2.42.0 — only needed if also self-hosting analytics)
curl -O https://cdn.amplitude.com/libs/analytics-browser-2.42.0-min.js.gz
```

**Option B: Pull from npm:**

```bash
pnpm pack @amplitude/plugin-session-replay-browser@1.28.1
# or
pnpm pack @amplitude/session-replay-browser@1.39.0
```

The `pnpm pack` command produces a `.tgz` tarball. Extract the tarball and locate the UMD bundle inside the `package/lib/scripts/` directory, for example, `plugin-session-replay-browser-1.28.1.umd.js`. Serve that file from your own origin.

For the latest version numbers, check:

- [npm: @amplitude/plugin-session-replay-browser](https://www.npmjs.com/package/@amplitude/plugin-session-replay-browser)
- [npm: @amplitude/session-replay-browser](https://www.npmjs.com/package/@amplitude/session-replay-browser)

### Serve the file

Host the file on your own CDN or static file server, then update your `<script>` tags:

```html
<!-- Before -->
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.42.0-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz"></script>

<!-- After -->
<script src="https://assets.yourdomain.com/libs/analytics-browser-2.42.0-min.js.gz"></script>
<script src="https://assets.yourdomain.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz"></script>
```

> **Tip:** Cache TTL
>
> If you plan to update the SDK version frequently, set a short cache TTL (1 to 5 minutes) on your file server. If you pin to a specific version and update manually, a longer TTL is fine.

---

## Part 2: Proxy API calls

Route SDK network requests through your own server so they don't go directly to `amplitude.com` endpoints. Your proxy server receives the request, forwards it to Amplitude's default endpoint, and returns Amplitude's response unchanged.

### How the proxy works

A minimal proxy implementation should:

1. Accept requests from the SDK at your custom URL.
2. Forward the full request body and all headers (except `Host`) to the corresponding Amplitude endpoint.
3. Return Amplitude's response to the SDK unchanged, including the status code, headers, and body.

Your proxy should be transparent. Don't strip, modify, or buffer the request or response payload. The SDK handles retries, so your proxy doesn't need to.

> **Tip:** Keep your API key server-side
>
> If you need to inject an `Authorization` header for a downstream service, inject the header in your proxy rather than hardcoding the API key in client-side code. Injecting the header server-side keeps credentials out of the browser.

### Analytics SDKs

Applies to: Browser SDK, Android (Kotlin) SDK, iOS (Swift) SDK, React Native SDK, Node.js SDK, Python SDK, Go SDK.

Use the `serverUrl` configuration option to point the SDK at your proxy:

```js
amplitude.init('API_KEY', {
  serverUrl: 'https://analytics.yourdomain.com/2/httpapi'
});
```

Your proxy should forward requests to the appropriate Amplitude endpoint:

| Region | Default endpoint |
| --- | --- |
| US | `https://api2.amplitude.com/2/httpapi` |
| EU | `https://api.eu.amplitude.com/2/httpapi` |
| US (batch) | `https://api2.amplitude.com/batch` |
| EU (batch) | `https://api.eu.amplitude.com/batch` |

Use the batch endpoints for high-volume environments. To enable batch mode, set `useBatch: true` on the SDK and point `serverUrl` at your proxy path that forwards to the batch endpoint:

```js
amplitude.init('API_KEY', {
  useBatch: true,
  serverUrl: 'https://analytics.yourdomain.com/batch'
});
```

**Remote config proxy (Browser SDK 2 only):**

Browser SDK 2 fetches remote configuration separately. To proxy those requests as well, use the `remoteConfig.serverUrl` option:

```js
amplitude.init('API_KEY', {
  serverUrl: 'https://analytics.yourdomain.com/2/httpapi',
  remoteConfig: {
    serverUrl: 'https://analytics.yourdomain.com/config'
  }
});
```

---

### Session Replay: Browser (Plugin and Standalone SDK)

Session Replay uses two separate endpoints. You can override each independently.

| Config option | US endpoint | EU endpoint | Purpose |
| --- | --- | --- | --- |
| `trackServerUrl` | `https://api-sr.amplitude.com/sessions/v2/track` | `https://api-sr.eu.amplitude.com/sessions/v2/track` | Send captured replay data |
| `configServerUrl` | `https://sr-client-cfg.amplitude.com/config` | `https://sr-client-cfg.eu.amplitude.com/config` | Fetch remote configuration |

**Session Replay Plugin:**

```js
sessionReplayPlugin({
  trackServerUrl: 'https://replay.yourdomain.com/sessions/v2/track',
  configServerUrl: 'https://replay.yourdomain.com/config'
});
```

**Session Replay Standalone SDK:**

```js
sessionReplay.init('API_KEY', {
  trackServerUrl: 'https://replay.yourdomain.com/sessions/v2/track',
  configServerUrl: 'https://replay.yourdomain.com/config'
});
```

---

### Session Replay: Mobile (Android, iOS, React Native)

The mobile Session Replay plugins don't support custom proxy URLs. The only routing option is `serverZone`, which switches between Amplitude's US and EU data centers. Data still flows directly to Amplitude's servers and doesn't pass through your own infrastructure.

```kotlin
// Android — set on the Amplitude SDK configuration
serverZone = ServerZone.EU
```

```swift
// iOS — set on the Amplitude SDK configuration
serverZone: .EU
```

---

## Content Security Policy (CSP)

If your app sets a Content Security Policy, update it when switching to self-hosted files and proxied endpoints.

| Directive | Default (Amplitude CDN) | With self-hosting |
| --- | --- | --- |
| `script-src` | `https://cdn.amplitude.com` | Your own file-serving domain |
| `connect-src` | `https://api-sr.amplitude.com` (US) or `https://api-sr.eu.amplitude.com` (EU) | Your proxy domain(s) |
| `worker-src` | `blob:` | Keep `blob:`, required by the Session Replay web worker |

**Example CSP (fully self-hosted):**

```text
Content-Security-Policy: script-src 'self' https://assets.yourdomain.com; connect-src 'self' https://analytics.yourdomain.com https://replay.yourdomain.com; worker-src 'self' blob:;
```

Because your proxy handles routing to Amplitude's US or EU endpoints, the CSP only needs to reference your own domain. The same policy works for both regions.

================================================================================
# Manage privacy settings for Session Replay
URL: https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay
================================================================================

# Manage privacy settings for Session Replay

Session Replay privacy settings control which user data appears in a replay and which data Amplitude masks. Configure masking, blocking, and PII handling to meet your organization's legal and security requirements. After you configure these settings, Session Replay applies them consistently across every session.

When these privacy settings are active, Amplitude masks the user data you specify in all session replays you create and view. Masking data prevents Amplitude from receiving it from your product. Masking doesn't remove the data from your own product data repository.

## Masking levels

Session Replay provides three presets for masking sensitive data in your screen recordings. You can also implement custom overrides when necessary.

- **Medium**: This is the default option for Session Replay privacy settings. When selected, Medium masks all form fields and text inputs. Amplitude captures all other text as-is.
- **Light**: This option is for companies that retain very little sensitive customer data, and for those who want to start quickly and selectively choose which fields to mask. Selecting this option masks only a subset of sensitive inputs, such as passwords, credit card numbers, telephone numbers, and email addresses. Examples of companies that might choose this option are business productivity app developers, restaurant- or appointment-booking software companies, and ecommerce sites.
- **Conservative**: This option is for companies that retain a large amount of sensitive customer data. Selecting this option masks all text and all form fields, including HTML text, user input, and links. Conservative masking doesn't apply to text in pictures, videos, thumbnails, or other static assets. [Use CSS Selectors](https://www.w3schools.com/cssref/css_selectors.php) to exclude any pictures, videos, or thumbnails that contain sensitive information. Examples of companies that might choose this option are financial services firms, CRM systems, online betting companies, geospatial technology companies, and companies in the healthcare and medical technology industries. In these sectors, the inadvertent release of sensitive user data could have serious repercussions.

Changes you make to these privacy levels take precedence over privacy definitions set in the SDK.

> **Warning:** HTML attribute masking limitation
>
> Session Replay masking applies to text content and form inputs, but doesn't mask HTML attribute values. Attributes such as `alt`, `title`, `placeholder`, `aria-label`, `value`, and custom `data-*` attributes remain visible in replays even when you enable masking. If your application stores sensitive information in HTML attributes, remove or obfuscate that data before it reaches Session Replay.

> **Note:** React Native masking options
>
> React Native Session Replay supports three masking levels through `privacyConfig.maskLevel` on the standalone SDK: `light` (sensitive native text inputs), `medium` (all `TextInput` fields; this is the default), and `conservative` (`TextInput` plus standard `Text` content). Remote masking configuration on the Session Replay settings page takes precedence over the SDK. Wrap a view with `AmpMaskView` when you need to mask, unmask, or block a specific region.
>
> Session Replay doesn't automatically mask text that React Native renders outside standard native text views, including `react-native-svg`, Shopify Skia, and canvas-based renderers. Wrap those regions in `AmpMaskView`.
>
> On Android, `light` doesn't reliably identify credit-card fields. Use `medium` or `conservative`, or wrap the field in `AmpMaskView`, for cross-platform coverage.
>
> Android and iOS resolve `AmpMaskView` differently. On Android, an `amp-unmask` nested inside a masked region re-reveals the content it wraps. On iOS, that content stays masked. For the full comparison, go to [Platform differences in masking](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk#platform-differences-in-masking).
>
> For setup details, go to [Mask onscreen data](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk#mask-onscreen-data) in the standalone SDK, or [Mask onscreen data](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin#mask-onscreen-data) in the plugin documentation.

## Set your privacy level

To set the Session Replay privacy level, navigate to _Settings > Organizational Settings > Session Replay Settings_ and select the appropriate project. Each project has its own settings. You can always view a summary of your masking level and overrides for each project on the main Session Replay Settings page.

### Override preset policy levels

You can override the default masking settings for individual elements by editing the matching [CSS selectors](https://www.w3schools.com/cssref/css_selectors.php) of those elements.

To override masking settings, right-click on your application and select Inspect mode. Under _Masking Overrides_, enter the CSS selector you want to change and select **+ Add Selector**. You can use this process to mask, unmask, or exclude individual elements.

Unmasking an element also unmasks its child elements. If needed, you can re-mask these child elements using the process above. However, when you mask an element using CSS selectors, Amplitude also masks its child elements. You can't then unmask these child elements.

When you exclude an element using CSS selectors, Amplitude replaces the element with an empty placeholder element of the same dimensions. Amplitude also excludes any child elements.

#### mask

![Diagram showing that masking a parent element masks its child elements, which you can't unmask](https://amplitude.com/docs/images/session-replay/image2.png)

#### unmask

![Diagram showing that you can mask or exclude child elements after unmasking a parent element](https://amplitude.com/docs/images/session-replay/image1.png)

#### exclude

![Diagram showing that excluding a parent element excludes its child elements, which you can't mask or unmask](https://amplitude.com/docs/images/session-replay/image3.png)

> **Tip:** Avoid site performance issues with masking
>
> If you experience a decrease in site performance due to the number of [masking](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#mask-on-screen-data) rules you create, Amplitude recommends excluding or blocking content with the `.amp-block` class, rather than masking it.
>
> Blocking or excluding content replaces the element with a placeholder of the same dimensions.

## How Session Replay resolves conflicts between the SDK and the UI

When the SDK and the Session Replay settings page conflict on how to handle a particular element (whether Amplitude should mask, unmask, or exclude it), the Session Replay settings page takes precedence.

For example, imagine you have used the Session Replay settings page to mask `.selector1` and unmask `.selector2`. An engineer then changes the SDK to mask `.selector3`, and at the same time inadvertently unmasks `.selector1`.

In this case, Session Replay combines the settings from the SDK and the UI, but the settings specified for `.selector1` in the UI take precedence:

|  | .selector1 | .selector2 | .selector3 |
| --- | --- | --- | --- |
| Session Replay settings | MASK | UNMASK |  |
| SDK settings | UNMASK |  | MASK |
| End results | MASK | UNMASK | MASK |

> **Note:** Remote configuration
>
> If you enable remote configuration and it fails to load, Session Replay doesn't capture any sessions. This behavior ensures that Amplitude respects any privacy settings you define in the Admin interface, and that you don't accidentally capture sensitive data.

### CSS selectors

Session Replay's configuration supports many types of [CSS Selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors). Specify an element tag (`h1` or `textarea`), a class name (`.hidden`), or a data attribute.

Data attributes may be useful if your class names change often due to hashing. To use data attributes, add a custom attribute like `data-amp-unmask` or `data-amp-mask` to any HTML element. For example, `<textarea data-amp-unmask></textarea>`. Then enclose the attribute in square brackets when you specify the selector, `[data-amp-unmask]`.

================================================================================
# Best practices for managing user consent
URL: https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent
================================================================================

# Best practices for managing user consent

When you use Session Replay, you must disclose the recording in your privacy policy and capture user consent where local privacy laws require it. These best practices cover how to word your privacy policy disclosure, set up cookie banners and consent management tools, and apply Amplitude's built-in privacy controls.

## Disclosure and consent

Session Replay reconstructs and analyzes real user interactions on your site or app. Some jurisdictions require a notice or consent for this kind of tracking.

## Inclusions for your privacy policy

Amplitude recommends that you update your privacy policy to clearly explain:

- That you use Session Replay technology.
- The kind of data you collect, such as clicks, navigation patterns, or form interactions.
- The reason you collect this data, such as to improve usability, troubleshoot issues, or better understand user behavior.
- How you store, process, and protect data.
- The options that users have to opt out, if applicable.

### Sample disclosure language

Modify the following examples to match your company's tone and policy structure.

> We may use cookies and similar technologies to collect information about our customers' interactions with our products and services in a manner that allows us to reproduce and fix issues and to identify areas of improvement for our products and services. You can opt out of the use of this software by contacting us at privacy@company.com.

> We use session replay technology to help us understand how users interact with our website and improve their experience. This technology captures user interactions, such as clicks, scrolling, and typing behavior, so we can identify usability issues and optimize our content. Sensitive information is automatically masked, and we do not use Session Replay to collect or store passwords, credit card numbers, or other sensitive data.

## Cookie banners or consent management tools

In regions that require prior consent, like the EU, include Session Replay in your cookie consent banner or Consent Management Platform (CMP). Amplitude's Session Replay SDK integrates Session Replay and its associated cookies with your CMP.

### Cookie and consent banner tips

Apply the following best practices when you update your banners:

- Categorize Session Replay under "analytics" or "functional" cookies. Session Replay cookies are **first-party** cookies, and Amplitude never uses your data for its own purposes.
- Don't enable Session Replay by default before consent, if your local laws require consent.
- Give users clear control over enabling or disabling Session Replay.
- Consider including a link to your privacy policy or a dedicated Session Replay information page.

### Sample banner wording

Modify the following examples to match your company's tone and style.

> We use cookies on our websites. Your interactions with our website and associated personal data may be collected by us in accordance with our Privacy Policy \[hyperlink to privacy policy that includes session replay disclosure\].

> We use cookies to personalize content and analyze traffic. We also use tools like session replay to better understand how users navigate our site and improve their experience. You can choose which cookies to allow.

## Amplitude's privacy controls

To help you stay compliant, Session Replay includes:

- [Privacy settings](https://amplitude.com/blog/session-replay-privacy) to fit your specific privacy requirements.
- Custom masking options that let you define which elements Session Replay captures or excludes.
- Configurable data retention to meet your company's data lifecycle policies.

## Related resources

- [Building a Privacy-first Session Replay with Amplitude](https://amplitude.com/blog/session-replay-privacy)
- Amplitude's [Trust](https://amplitude.com/trust) page
- [Session Replay Privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay)

For more detailed legal guidance, consult with your legal team or privacy counsel.

================================================================================
# Session Replay Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk
Updated: 2024-11-14
================================================================================

# Session Replay Standalone SDK

- **Package:** `@amplitude/session-replay-browser` ([npm](https://www.npmjs.com/package/@amplitude/session-replay-browser))
- **Latest version:** 1.50.0

> **Note:** Session Replay instrumentation
>
> Session Replay isn't enabled by default, and requires setup beyond the standard Amplitude instrumentation.

The Session Replay standalone SDK adds session recording to your site independently of the Amplitude Browser SDK. If you use a provider other than Amplitude for in-product analytics, choose this option. If your site already uses the Amplitude Browser SDK, use the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin).

> **Info:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on web page performance by:
>
> - Processing asynchronously through webhooks (if enabled) for efficient compression and optimized bundle sizes.
> - Using batching and lightweight compression to reduce network connections and bandwidth.
> - Optimizing DOM processing.

## Bundle size

The Session Replay standalone SDK adds to your application's bundle size.

For current bundle size information, check the [npm package page](https://www.npmjs.com/package/@amplitude/session-replay-browser) or [BundlePhobia](https://bundlephobia.com/package/@amplitude/session-replay-browser).

## Runtime performance

Session Replay runs asynchronously and processes replay data in the background to avoid blocking the main thread. Performance characteristics include:

- **DOM capture**: DOM snapshot capture typically adds less than 5ms of processing time for each page interaction. Initial page load snapshot capture takes 10-50ms depending on page complexity.
- **Memory usage**: Session Replay stores replay events in memory or IndexedDB (configurable using `storeType`). Memory usage scales with session length and page complexity, typically ranging from 1-10 MB for each active session.
- **CPU impact**: With default settings, Session Replay uses less than 2% of CPU time during normal operation. Amplitude defers compression operations to browser idle periods when `performanceConfig.enabled` is `true` (default).
- **Network bandwidth**: Amplitude compresses replay data before upload, typically reducing payload size by 60-80%. Amplitude batches network requests and sends them asynchronously.

## Performance optimization

To optimize Session Replay performance:

- Enable `useWebWorker` to move compression off the main thread, reducing CPU impact on the main thread.
- Configure `performanceConfig.timeout` to control when deferred compression occurs.
- Use `sampleRate` to reduce the number of sessions captured, which directly reduces CPU and memory usage.
- Set `storeType` to `memory` if you don't need persistence across page reloads, reducing IndexedDB overhead.

For detailed performance testing results, refer to the [Session Replay performance testing blog post](https://amplitude.com/blog/session-replay-performance-testing).

Session Replay captures changes to a page's Document Object Model (DOM), including elements in the shadow DOM, then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the page's DOM. As the user interacts with the page, Session Replay captures each change to the DOM as a diff. When you watch the replay of a session, Session Replay applies each diff back to the original DOM in sequential order to construct the replay. Session replays have no maximum length.

## Before you begin

Session Replay Standalone SDK requires that:

1. Your application is web-based.
2. You provide a session identifier to the SDK at initialization and call `setSessionId` when it changes. The SDK uses this ID to bucket replay data. For session ID matching, use the same session identifier on analytics events and in the SDK. With [time-based event matching](https://amplitude.com/docs/session-replay/session-matching#time-based-event-matching) only, the Session Replay `sessionId` can be a frontend-generated time bucket (for example, an hour-aligned Unix timestamp in milliseconds) that doesn't appear on analytics events.
3. You can provide a device ID to the SDK.
4. The `Device ID` you pass to the Standalone SDK must match the device ID on your analytics events.

The Standalone SDK doesn't provide session management capabilities. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`.

## Quickstart

Install the plugin with npm or yarn.

> **Info:** Unified SDK
>
> Install the [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk) to access the Experiment SDK along with other Amplitude products (Analytics, Session Replay). The Unified SDK provides a single entry point for all Amplitude features and handles the initialization and configuration of all components.

#### npm

```bash
# Install Session Replay SDK only
npm install @amplitude/session-replay-browser --save

# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified
```

#### yarn

```bash
# Install Session Replay SDK only
yarn add @amplitude/session-replay-browser

# Or install Unified SDK to get access to all Amplitude products
yarn add @amplitude/unified
```

Configure your application code.

1. Call `sessionReplay.init` to begin collecting replays. Pass the API key, session identifier, and device identifier.
2. When the session identifier changes, pass the new value to Amplitude with `sessionReplay.setSessionId`.
3. Amplitude automatically creates the `[Amplitude] Replay Captured` event to link replays with your analytics data. Refer to [Session Replay ID](#session-replay-id) for more information.

#### Standalone SDK

```js
import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'

const AMPLITUDE_API_KEY = "key"

// Configure the SDK and begin collecting replays
await sessionReplay.init(AMPLITUDE_API_KEY, {
 deviceId: "<string>",
 sessionId: "<string | number>",
 optOut: "<boolean>",
 sampleRate: "<number>"
}).promise;

// Call whenever the session id changes
await sessionReplay.setSessionId(sessionId).promise;
```

#### Unified SDK

```js
import { initAll, sessionReplay } from "@amplitude/unified";

// Initialize the Unified SDK with your API key
// The Unified SDK automatically handles:
// - Device ID and Session ID management
// - Session ID changes
// - Event property collection and tracking
initAll("YOUR_API_KEY", {
  sessionReplay: {
    sampleRate: "<number>",
  },
});

// Call session replay APIs
sessionReplay.shutdown();
```

> **Info:**
>
> Session Replay instrumentation happens in the context of an Amplitude project. Amplitude defines your replay quota at the organization level. You may have multiple Session Replay implementations across multiple projects, each with its own sample rate, that pull from the same quota.

You can also use script tags to instrument Session Replay:

```js
<script src="https://cdn.amplitude.com/libs/session-replay-browser-1.50.0-min.js.gz"></script>
<script>
window.sessionReplay.init(AMPLITUDE_API_KEY, {
    deviceId: "<string>",
    sessionId: "<string | number>",
    sampleRate: "<number>"
    //...other options
})

// Call whenever the session id changes
window.sessionReplay.setSessionId(sessionId);
</script>
```

## Session Replay ID

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. This event includes the `[Amplitude] Session Replay ID` property, which links the replay to your analytics data. Manual instrumentation isn't required.

`[Amplitude] Session Replay ID` is a unique identifier for the replay, and differs from `[Amplitude] Session ID`, which identifies the user's session by default.

The session replay ID has the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, `deviceId` and custom session ID string values can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

> **Info:**
>
> Amplitude links replays with a session replay ID. To combine multiple sessions into a single replay, ensure each session references the same device ID and session ID.

> **Note:** Legacy implementations
>
> If you have a legacy implementation that manually adds the `[Amplitude] Session Replay ID` property to events using `getSessionReplayProperties()`, this continues to work. However, Amplitude recommends the automatic `[Amplitude] Replay Captured` event.

> **Warning:** Not seeing replays?
>
> If replays don't appear in the Amplitude UI, check that the `[Amplitude] Replay Captured` event appears in your project. If you don't see this event, contact Amplitude support.

## Configuration

Pass the following configuration options when you initialize the Session Replay SDK.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `deviceId` | `string` | Yes | `undefined` | Sets an identifier for the device running your application. |
| `sessionId` | `string | number` | Yes | `undefined` | Sets an identifier for the user's current session. Use a Unix timestamp in milliseconds (`number`) for standard session tracking, or a custom string for [custom session definitions](https://amplitude.com/docs/session-replay/session-matching#requirements-for-custom-session-definitions). Custom string values must follow the [accepted character set](#session-replay-id). |
| `sampleRate` | `number` | No | `0` | Controls how many sessions Amplitude 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. Sample rates as small as six decimal places (`0.000001`) work. |
| `optOut` | `boolean` | No | `false` | Sets permission to collect replays for sessions. A value of true prevents Amplitude from collecting session replays. |
| `flushMaxRetries` | `number` | No | `5` | Sets the maximum number of retries for failed upload attempts. This applies only to errors that Amplitude can retry. |
| `logLevel` | `number` | No | `LogLevel.Warn` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. Sets the log level. |
| `loggerProvider` | `Logger` | No | `Logger` | Sets a custom `loggerProvider` class from the Logger to emit log messages to your destination. |
| `serverZone` | `string` | No | `US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in the EU data center. |
| `privacyConfig` | `object` | No | `undefined` | Supports advanced masking configurations with CSS selectors. Refer to [Mask on-screen data](#mask-on-screen-data) for more information. |
| `applyBackgroundColorToBlockedElements` | `boolean` | No | `false` | If true, applies a background color to blocked elements for visual masking. This helps visualize which elements Amplitude blocks from capture in the replay. |
| `debugMode` | `boolean` | No | `false` | Adds an additional debug event property to help debug instrumentation issues (such as mismatching apps). Amplitude recommends this only for debugging initial setup, not for production. |
| `configServerUrl` | `string` | No | `undefined` | Specifies the endpoint URL to fetch remote configuration. If provided, it overrides the default server zone configuration. |
| `trackServerUrl` | `string` | No | `undefined` | Specifies the endpoint URL to send session replay data. If provided, the SDK forwards requests there instead of to the default SR endpoint. |
| `shouldInlineStylesheet` | `boolean` | No | `true` | If Amplitude inlines stylesheets, it stores the contents of the stylesheet. During replay, Amplitude uses the stored stylesheet instead of fetching it remotely. This prevents replays from appearing broken due to missing stylesheets. Inlining stylesheets may not work in all cases. If this is undefined, Amplitude inlines stylesheets. |
| `storeType` | `string` | No | `idb` | Specifies how Amplitude stores replay events. `idb` uses IndexedDB to persist replay events when the SDK can't send all events during capture. `memory` stores replay events only in memory, so events are lost when the page closes. If IndexedDB is unavailable, the system falls back to memory. |
| `performanceConfig.enabled` | `boolean` | No | `true` | If enabled, Amplitude defers event compression to occur during the browser's idle periods. |
| `performanceConfig.timeout` | `number` | No | `undefined` | Optional timeout in milliseconds for the requestIdleCallback API. If specified, this value sets a maximum time for the browser to wait before executing the deferred compression task, even if the browser isn't idle. |
| `useWebWorker` | `boolean` | No | `false` | Uses a web worker to compress replay events. This improves performance by moving compression off the main thread. |

### API endpoints

Session Replay uses the following API endpoints:

- **Data ingestion**:

  - US: `https://api-sr.amplitude.com/sessions/v2/track`.
  - EU: `https://api-sr.eu.amplitude.com/sessions/v2/track`.
  - Session Replay sends captured replay data to these endpoints.
- **Remote configuration**:

  - US: `https://sr-client-cfg.amplitude.com/config`.
  - EU: `https://sr-client-cfg.eu.amplitude.com/config`.
  - Session Replay fetches remote configuration from these endpoints.

If you set up a domain proxy, forward requests to these endpoints. You can override these defaults using the `trackServerUrl` and `configServerUrl` configuration options.

### Mask on-screen data

The Session Replay SDK offers three ways to mask user input, text, and other HTML elements.

| Element | Description |
| --- | --- |
| `<input>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the class `.amp-unmask`. For example: `<input class="amp-unmask">`. |
| text | To mask text within non-input elements, add the class `.amp-mask`. For example, `<p class="amp-mask">Text</p>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the class `.amp-block`. For example, `<div class="amp-block"></div>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |

Session Replay supports setting a masking level on the [Session Replay Settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) screen in Amplitude. This includes Light, Medium, and Conservative settings.

Session Replay settings also enable remote masking overrides. These enable users in your organization to configure or update masking after implementation.

In the event of a conflict, Session Replay defers to the remote setting. For example:

|  | .selector-1 | .selector-2 | .selector-3 |
| --- | --- | --- | --- |
| Local setting | `mask` | -- | `mask` |
| Remote setting | `unmask` | `unmask` | -- |
| Result | `unmask` | `unmask` | `mask` |

In this example, `.selector-1` has a local setting and a remote setting. The result follows the remote setting, and overrides the setting in the SDK or plugin implementation.

Specify elements to block or mask in the `privacyConfig` object during configuration.

```js
// This configuration blocks .no-track and #ads, sets the default mask level,
// and defines the mask and unmask selectors.
await sessionReplay.init(AMPLITUDE_API_KEY, {
  privacyConfig: {
    blockSelector: ['.no-track', '#ads'],
    defaultMaskLevel: 'medium',
    maskSelector: ['.sensitive-data', '.user-email'],
    unmaskSelector: ['.public-info', '#main-content']
  }
}).promise;
```

#### CSS selectors

Session Replay's configuration supports many types of [CSS Selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors). Specify an element tag (`h1` or `textarea`), a class name (`.hidden`) or a data attribute.

Data attributes may be useful if your class names change often due to hashing. To use  data attributes, add a custom attribute like `data-amp-unmask` or `data-amp-mask` to any HTML element. For example, `<textarea data-amp-unmask></textarea>`, then enclose the attribute in square brackets when you specify the selector, `[data-amp-unmask]`.

> **Note:** Remote configuration
>
> If remote configuration is enabled, and fails to load, Session Replay doesn't capture any sessions. This ensures that Amplitude respects any privacy settings you define in the Admin interface, and you don't accidentally capture sensitive data.

### User opt-out

Session Replay provides an opt-out configuration option. When passed as part of initialization, this prevents Amplitude from collecting session replays. For example:

```js
// Pass a boolean value to indicate a users opt-out status
await sessionReplay.init(AMPLITUDE_API_KEY, {
  optOut: true,
}).promise;
```

### Content Security Policy (CSP)

If your web application uses a strict Content Security Policy, add the following directives:

#### Required CSP directives

```text
script-src: https://cdn.amplitude.com;
connect-src: https://api-secure.amplitude.com;
worker-src: blob:;
```

#### CSP directives reference

| Directive | Domain | Required | Description |
| --- | --- | --- | --- |
| `script-src` | `https://cdn.amplitude.com` | Yes, if using CDN | Allows loading the Session Replay SDK from Amplitude's CDN. |
| `connect-src` | `https://api-secure.amplitude.com` | Yes (US) | Allows sending replay data to Amplitude's US servers. |
| `connect-src` | `https://api.eu.amplitude.com` | Yes (EU) | Allows sending replay data to Amplitude's EU servers. Required if you set `serverZone: "EU"`. |
| `worker-src` | `blob:` | Yes, if using web workers | Required if you enable the `useWebWorker` option for replay event compression. |

#### API endpoints

Session Replay sends data to the following endpoints:

| Region | Endpoint | Purpose |
| --- | --- | --- |
| US (default) | `https://api-secure.amplitude.com/sessions/track` | Replay data ingestion. |
| EU | `https://api.eu.amplitude.com/sessions/track` | Replay data ingestion for EU data residency. |
| US (default) | `https://api-secure.amplitude.com/sessions/config` | Remote configuration (sample rate settings). |
| EU | `https://api.eu.amplitude.com/sessions/config` | Remote configuration for EU data residency. |

#### Example CSP header

For US data center:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-secure.amplitude.com; worker-src 'self' blob:;
```

For EU data center:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api.eu.amplitude.com; worker-src 'self' blob:;
```

> **Tip:**
>
> If you use the `configServerUrl` or `trackServerUrl` configuration options to specify custom endpoints, add those domains to your `connect-src` directive instead.

### 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
// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
  serverZone: "EU",
}).promise;
```

### Sampling rate

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

```js
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
  sampleRate: 0.01,
}).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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, refer to [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-and-analyze-replays).

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 a conflict occurs, Session Replay defaults to the remote setting. For more information, refer to [Account Settings](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings).

### Disable replay collection

After enabled, Session Replay runs on your site until either:

- The user leaves your site.
- You call `sessionReplay.shutdown()`.

Call `sessionReplay.shutdown()` before a user navigates to a restricted area of your site to disable replay collection while the user is in that area.

Call `sessionReplay.init(API_KEY, {...options})` to re-enable replay collection when the user returns to an unrestricted area of your site.

You can also use a feature flag product like Amplitude Experiment to create logic that enables or disables replay collection based on criteria like location. For example, you can create a feature flag that targets a specific user group, and add that to your initialization logic:

```js
import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'

const AMPLITUDE_API_KEY = <...>
await sessionReplay.init(AMPLITUDE_API_KEY, {
 deviceId: <string>,
 sessionId: <string | number>,
 optOut: <boolean>,
 sampleRate: <number>
}).promise;
```

## Data retention

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

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### 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](https://support.amplitude.com).

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](https://amplitude.com/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 Amplitude 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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

Session Replay doesn't set cookies on the user's browser. Instead, it relies on a browser storage option called [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) by default. This option enables continuous replay collection during a session in which the user navigates browser tabs or closes and reopens a tab. The SDK cleans up the data it stores in IndexedDB and shouldn't impact the user's disk space.

If the environment doesn't support IndexedDB, Session Replay falls back to an in-memory storage option. In-memory storage is less durable and data is lost  when the user closes their browser window. Set the config option `storeType` to `'memory'` to force in-memory storage.

If a user opts out of all cookies on your site, use the `optOut` configuration option to disable replay collection for that user.

### IndexedDB best practices

To ensure that IndexedDB is initialized and working properly:

- Review CSP headers to ensure they're not overly restrictive. Ensure `default-src` and `script-src` directives allow necessary sources.
- Perform IndexedDB operations within the same origin. Cross-origin restrictions can block IndexedDB operations.
- Confirm that users use a modern browser that supports IndexedDB. Amplitude recommends the latest versions of Chrome, Firefox, Safari, Edge, or Opera.

## Known limitations

Note the following limitations as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument your marketing site and web application as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on the marketing site, and logs in to the web application.
  - Amplitude captures both sessions.
  - The replay for each session appears in the host project.
- Session Replay can't capture the following HTML elements:

  - Canvas.
  - WebGL.
  - `object` tags including plugins like Flash, Silverlight, or Java. Session Replay supports `object type="image"`.
  - Lottie animations.
  - Cross-origin `<iframe>` elements that don't load the Session Replay SDK with `crossOriginIframes.enabled: true` (for example, third-party embeds like Stripe or Google Maps). To capture first-party cross-origin iframes, go to [Cross-origin iframe recording](https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes).
  - Assets that require authentication, like fonts, CSS, or images.
- Session Replay isn't compatible with ad blocking software.

## Troubleshooting

For more information about individual statuses and errors, refer to the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

### CSS styling doesn't appear in replay

When Amplitude captures a replay, it doesn't download and store CSS files or other static assets that are part of your application or site. Session Replay stores references to these files, and uses those references while it reconstructs the replay. In some situations, the styling present in the replay may differ from your application for the following reasons:

- Assets on your site move or change name. This can happen when you deploy a new version of your application.
- Assets on your site sit behind access controls that prevent Amplitude from fetching them.

To help resolve CSS loading issues:

- Ensure your domain is publicly accessible. If you store assets on `localhost`, try moving them to a staging environment.
- Your CDN should keep track of old stylesheets for older replays. If the content of the same stylesheet changes over time, try to append a unique string or hash to the asset URL. For example, `stylesheet.css?93f8b89`.
- Add `app.amplitude.com` or `app.eu.amplitude.com` to the list of domains that your server's CORS configuration permits.

### Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This happens when a user closes their browser or browser tab and `[Amplitude] End Session` occurs, but the Browser SDK and Session Replay plugin haven't yet processed it. When the user visits that page again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

Session replays may not appear in Amplitude due to:

- Content security policy
- Blocked JavaScript
- No events triggered through the browser SDK in the current session
- Sampling

#### Local development and focus state

The Session Replay SDK and plugin capture only the page that's in focus. When you develop locally with the browser console open, focus states may not work as expected. If you don't see replays in Amplitude, try to enable `debugMode`. In this mode, Session Replay ignores the focus handle and enables extra debugging information.

```js
const sessionReplayTracking = window.sessionReplay.plugin({
 debugMode: true,  
 sampleRate: 1, 
 });
```

#### Content security policy

When you add the Session Replay script to your site, visit a page on which the Session Replay SDK is running, and open your browser's developer tools.

Check for any error messages in the JavaScript console that contain the text `Content Security Policy`. For example, `Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy`.

To resolve this error, update your site's content security policy to allow connection to Amplitude's APIs.

#### Blocked JavaScript

Browser extensions or network security policy may block the Session Replay SDK. Check your browser's developer tools to see if requests fail, and if so, add an exception for the blocked domains.

#### Sampling

As mentioned above, the default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information see, [Sampling rate](#sampling-rate).

#### Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the `[Amplitude] Session Replay ID` property, only that one event in the session has it. Reasons why `[Amplitude] Session Replay ID` may not be present in an event include:

If you instrument an event with a source different from the source you connect to Session Replay. For example, your application may send events from a backend source, rather than the Browser SDK.

### Session Replay processing errors

In general, replays appear within minutes of ingestion. Delays or errors may result from one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a user bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If Session Replay isn't implemented on all pages a user visits, their session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 30 days, or 90 days if you purchase extra volume).

================================================================================
# Cross-origin iframe recording
URL: https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes
Updated: 2025-06-04
================================================================================

# Cross-origin iframe recording

The Session Replay Browser SDK can capture DOM changes inside cross-origin `<iframe>` elements and merge them into the parent page's replay stream. Both the parent page and each child iframe page must load the SDK with `crossOriginIframes.enabled: true`.

This article covers configuration, privacy behavior, limitations, and troubleshooting.

> **Note:** Browser SDK only
>
> Cross-origin iframe recording applies to the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) and [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk). Mobile Session Replay SDKs don't support this feature.

## How it works

When you enable cross-origin iframe recording on the parent page, the SDK:

1. Watches for `<iframe>` elements added to the DOM.
2. Sends `start` and `stop` signals to child frames over `postMessage`.
3. Relays child rrweb events into the parent replay stream so the replay viewer can reconstruct both frames from a single session.

The child SDK detects when it runs inside an iframe and waits for a start signal from the parent before it begins recording.

## Setup

Load the Session Replay SDK on **both** the parent page and each child iframe page you want to capture.

### Parent page

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";

sessionReplay.init("API_KEY", {
  deviceId: "DEVICE_ID",
  sessionId: SESSION_ID,
  sampleRate: 1,
  crossOriginIframes: {
    enabled: true,
    coordinateChildren: true,
  },
});
```

If you use the Browser SDK plugin, pass the same options to `sessionReplay.plugin()`:

```javascript
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";

const replay = sessionReplayPlugin({
  crossOriginIframes: {
    enabled: true,
    coordinateChildren: true,
  },
});

amplitude.add(replay);
amplitude.init("API_KEY", { deviceId: "DEVICE_ID" });
```

### Child iframe page

Initialize the SDK with the **same** `apiKey`, `deviceId`, and `sessionId` as the parent. Enable cross-origin iframes, but don't set `coordinateChildren` on the child:

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";

sessionReplay.init("API_KEY", {
  deviceId: "DEVICE_ID",
  sessionId: SESSION_ID,
  sampleRate: 1,
  crossOriginIframes: { enabled: true },
});
```

Pass `sessionId` and `deviceId` to the child through the iframe URL query string when you set the iframe `src`.

## Configuration options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `crossOriginIframes.enabled` | `boolean` | `false` | Enables cross-origin iframe recording on the page. Set to `true` on both parent and child pages. |
| `crossOriginIframes.coordinateChildren` | `boolean` | `true` | When `true`, the parent SDK sends start/stop signals to child iframes and keeps their recording lifecycle in sync. Set to `false` to manage child recording yourself. Applies to the parent page only. |

## Privacy

The child page's rrweb instance performs its own DOM serialization. The parent's privacy config (mask levels, block selectors, and so on) **doesn't** automatically apply inside the iframe. Configure privacy settings independently on each child page.

## Limitations

- **Third-party iframes** (for example, Stripe, Google Maps, or YouTube) can't be captured. You control only pages where you install the Session Replay SDK.
- **`coordinateChildren: false`** opts out of the parent coordinator. In this mode, the child SDK doesn't start recording until you manage its lifecycle directly.
- **Same-origin iframes** don't require cross-origin configuration, but enabling `crossOriginIframes` on both pages still works.

## Validate your setup

1. Confirm the parent and each child page load the Session Replay SDK with `crossOriginIframes.enabled: true`.
2. Use the same `apiKey`, `deviceId`, and `sessionId` on both pages.
3. Add or navigate to the child iframe after the parent SDK initializes.
4. Interact inside the iframe, then open the session in Amplitude's replay viewer.

For local cross-origin testing, serve the parent and child from different origins (different ports or hostnames). A public HTTPS parent can't embed an `http://localhost` child because of mixed content and browser Local Network Access restrictions.

## Troubleshooting

### The iframe is blank in the live page

| Symptom | Likely cause |
| --- | --- |
| Blank iframe from a public parent | Child URL uses `http://localhost` or another blocked origin. Serve the child over public HTTPS. |
| "Refused to connect" | Child URL is wrong or unreachable. Verify the iframe `src` and that the child origin allows embedding. |
| Placeholder only | Parent didn't inject an iframe yet. Add the iframe in your app after the SDK initializes. |
| Empty iframe in replay | Child page doesn't load Session Replay (for example, a static demo page). Install the SDK on the child with `crossOriginIframes.enabled: true`. |

### The iframe is blank in the replay viewer

| Symptom | Likely cause |
| --- | --- |
| Short session looks empty | The first child merge may arrive ~1 second after iframe injection. Record a longer session and interact inside the iframe. |
| Missing styles or low contrast | CSS didn't replay correctly — not missing DOM. Check external stylesheets, add `crossorigin="anonymous"` on `<link rel="stylesheet">`, and allow `app.amplitude.com` in CORS. Go to [CSS styling doesn't appear in replay](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#css-styling-doesnt-appear-in-a-replay). |
| iframe shell with no content | Child DOM merged through incrementals but a later checkout snapshot may omit iframe children. If capture looks correct in raw events but replay shows an empty frame, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new) with the session replay ID. |

## Related documentation

- [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin)
- [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk)
- [Session Replay ingestion monitor](https://amplitude.com/docs/session-replay/ingestion-monitor)

================================================================================
# Implement Session Replay with Google Tag Manager
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager
Updated: 2024-11-01
================================================================================

# Implement Session Replay with Google Tag Manager

Instrumenting Amplitude Session Replay with Google Tag Manager requires a different procedure than the standard [Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin).

> **Note:**
>
> This article applies to **client-side** GTM instrumentations only.

## Enable Session Replay

To instrument Session Replay with Google Tag Manager:

1. Add the [Google Tag Manager Web Template for Amplitude Analytics Browser SDK](https://amplitude.com/docs/data/source-catalog/google-tag-manager) if you haven't enabled it.

> **Note:** Update the Amplitude tag template
>
> The latest version of the Amplitude Analytics Browser SDK template includes a Session Replay toggle.

2. In Google Tag Manager, create a new tag using the Amplitude template, or edit an existing tag based on the template.
3. In the tag's _Initialization_ section, select **Enable Session Replay Plugin**.
4. In Amplitude, navigate to _Organization Settings > Session Replay Settings_. Update any [masking](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#mask-on-screen-data), [sample rate](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#sampling-rate), or other settings.

## Troubleshooting

Multiple instantiation of the Amplitude SDKs is a common problem with GTM and other code injection frameworks. Make sure the initialization logic runs only once in your app. Multiple instantiation can happen if:

- More than one "Init Tag" or another custom tag runs Amplitude.
- Another code injection framework (for example, SquareSpace or Bubble) also runs Amplitude.

This template uses the Amplitude Browser SDK Plugin. For troubleshooting help, refer to [Troubleshooting | Session Replay Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#troubleshooting).

================================================================================
# Session Replay Wrapper for Rudderstack
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-rudderstack-integration
Updated: 2025-03-18
================================================================================

# Session Replay Wrapper for Rudderstack

Amplitude provides a wrapper for integrating Rudderstack and Amplitude's Session Replay.

> **Note:**
>
> This integration snippet supports [Rudderstack Cloud-mode](https://www.rudderstack.com/docs/destinations/rudderstack-connection-modes/#cloud-mode).

## Install the wrapper

Use npm or yarn to install the package, which includes the Amplitude Session Replay SDK.

#### npm

```bash
npm install @amplitude/session-replay-browser --save
```

#### yarn

```bash
yarn add @amplitude/session-replay-browser
```

## Initialize Session Replay with Rudderstack

For information about the `sessionReplayOptions`, refer to the [Session Replay Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#configuration) section.

```js
import * as sessionReplay from "@amplitude/session-replay-browser";

amplitude.init(AMPLITUDE_API_KEY, user_id, config).promise.then(() => {
  window.rudderAnalytics.ready(function () {
    const rudderAnonymousId = rudderAnalytics.getAnonymousId();

    sessionReplay.init(AMPLITUDE_API_KEY, {
      deviceId: rudderAnonymousId,
      sessionId: rudderAnalytics.getSessionId(),
      sampleRate: 0.1, // 10% of sessions will be captured
    }).promise;
    sessionReplay.set(rudderAnalytics.getSessionId());
  });
});
```

## How Amplitude links replays to Rudderstack events

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. Amplitude sends this event directly to link replays with your analytics data. If you don't see this event in Amplitude, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Required field mapping

Amplitude maps the [Rudderstack Anonymous ID](https://www.rudderstack.com/docs/event-spec/standard-events/identify/#anonymous-id) to the [Amplitude Device ID](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues#instrumentation-basics), and the [Rudderstack Session ID](https://www.rudderstack.com/docs/sources/event-streams/sdks/session-tracking/) to the [Amplitude Session ID](https://amplitude.com/docs/data/sources/instrument-track-sessions#how-amplitude-defines-sessions). If you use another field for device ID, contact [Amplitude Support](https://support.amplitude.com).

The session replay ID has the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, the `deviceId` value can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. Rudderstack's anonymous ID is a UUID, which always complies with these requirements. If you use a custom value for `deviceId`, ensure it follows the accepted character set. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Troubleshooting

> **Warning:** Session replay and ad blockers
>
> Session Replay isn't compatible with ad blocking software.

For troubleshooting information, go to [Session Replay Standalone SDK | Troubleshooting](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#troubleshooting).

================================================================================
# Session Replay Plugin for Segment
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-wrapper-for-segment
Updated: 2024-09-19
================================================================================

# Session Replay Plugin for Segment

Amplitude provides a plugin that enables a one-line integration between Segment and Amplitude's Session Replay.

> **Note:**
>
> This plugin supports [Segment's Amplitude (Actions)](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/) destination only.
>
> To use Session Replay with [Segment's Amplitude (Classic) destination](https://segment.com/docs/connections/destinations/catalog/amplitude/), use the [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk).

## Install the plugin

Use npm or Yarn to install the package, which includes the Amplitude Session Replay SDK.

#### npm

```bash
npm install @amplitude/segment-session-replay-plugin --save
```

#### yarn

```bash
yarn add @amplitude/segment-session-replay-plugin
```

## Use

For information about the `sessionReplayOptions`, go to the [Session Replay Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#configuration) section.

```js
import { AnalyticsBrowser } from "@segment/analytics-next";
import { createSegmentActionsPlugin } from "@amplitude/segment-session-replay-plugin";

export const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: SEGMENT_API_KEY,
});

const segmentActionsPlugin = createSegmentActionsPlugin({
  segmentInstance: segmentAnalytics,
  amplitudeApiKey: AMPLITUDE_API_KEY,
  sessionReplayOptions: {
    logLevel: 4,
    sampleRate: 1,
    debugMode: true,
  },
});

segmentAnalytics.register(segmentActionsPlugin);
```

## Segment plugin architecture

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. The plugin sends this event directly to Amplitude to link replays with your analytics data. If you don't see this event in Amplitude, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## User ID to Device ID mapping

Following Segment's documentation, the plugin maps the Segment user ID to the Amplitude device ID. To find the device ID for replay captures, the plugin checks whether `userId` is set, and if not, the plugin uses `anonymousId`.

The session replay ID uses the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, the device ID value can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. Segment's `userId` and `anonymousId` values are UUIDs, which always comply with these requirements. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Troubleshooting

> **Warning:** Session replay and ad blockers
>
> Session Replay isn't compatible with ad blocking software.

For troubleshooting information, go to [Session Replay Standalone SDK | Troubleshooting](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#troubleshooting).

================================================================================
# Session Replay integration with Segment
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-integration-with-segment
Updated: 2025-03-04
================================================================================

# Session Replay integration with Segment

Session Replay supports other analytics providers. Use the following options to add Session Replay to a Segment-instrumented site.

- [Amplitude (Actions) destination](#amplitude-actions-destination).
- [Amplitude Classic destination (Device-mode)](#amplitude-classic-destination-device-mode).
- [Amplitude Classic destination (Cloud-mode)](#amplitude-classic-destination-cloud-mode).
- [Troubleshoot Segment integration](#troubleshoot-segment-integration).

> **Note:** Replay Captured event
>
> Amplitude creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. Amplitude receives this event directly, and Segment doesn't forward it. If this event doesn't appear in Amplitude, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Amplitude (Actions) destination

Amplitude (Actions) tracks sessions automatically. When a user starts a new session, Amplitude sets an `analytics_session_id` cookie on the user's browser. Configure your implementation to listen for changes to `analytics_session_id` using Segment's [Source Middleware](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/middleware/).

The following code snippet configures Session Replay with Segment's Amplitude (Actions) integration and updates the session ID when `analytics_session_id` changes.

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";
import { AnalyticsBrowser } from "@segment/analytics-next";

const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: "segment-key",
});

const AMPLITUDE_API_KEY = 'api-key' // must match that saved with Segment
const getStoredSessionId = () => {
 return cookie.get("analytics_session_id") || 0;
}

const user = await segmentAnalytics.user();
const storedSessionId = getStoredSessionId();

await sessionReplay.init(AMPLITUDE_API_KEY, { 
  sessionId: storedSessionId,
  deviceId: user.anonymousId()
}).promise;

// Add middleware to check if the session id has changed, 
// and update the session replay instance
segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
  const storedSessionId = getStoredSessionId();
  const nextSessionId = payload.obj.integrations['Actions Amplitude'].session_id || 0
  if (storedSessionId < nextSessionId) {
    cookie.set("analytics_session_id", nextSessionId);
    sessionReplay.setSessionId(nextSessionId);
  }
  next(payload);
});
```

## Amplitude Classic destination (Device-mode)

This version of the Amplitude destination installs the Amplitude JavaScript SDK (5.2.2) on the client and sends events directly to `api.amplitude.com`.

The Device-mode integration tracks sessions by default because it includes the amplitude-js SDK. The included SDK version (5.2.2) doesn't emit an event for session changes. Use Segment's middleware to update Session Replay when the session ID changes.

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";
import { AnalyticsBrowser } from "@segment/analytics-next";

const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: "segment-key",
});

const AMPLITUDE_API_KEY = 'api-key' // must match that saved with Segment
const getAmpSessionId = () => {
  const sessionId = window.amplitude.getInstance().getSessionId();
  cookie.set("analytics_session_id", sessionId);
  return sessionId;
};

// Wait for the amplitude-js SDK to initialize,
// then initialize session replay with the correct device id and session id
window.amplitude.getInstance().onInit(() => {
  const sessionId = getAmpSessionId();
  sessionReplay.init(AMPLITUDE_API_KEY, {
    deviceId: window.amplitude.getInstance().options.deviceId,
    sessionId: getAmpSessionId(),
  });
});

// Add middleware to check if the session id has changed, 
// and update the session replay instance
segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
  const nextSessionId = window.amplitude.getInstance().getSessionId();
  const storedSessionId = cookie.get("analytics_session_id") || 0;
  if (storedSessionId < nextSessionId) {
    cookie.set("analytics_session_id", nextSessionId);
    sessionReplay.setSessionId(nextSessionId);
  }
  next(payload);
});
```

## Amplitude Classic destination (Cloud-mode)

This version of the Amplitude destination sends events to Segment's backend, which forwards them to Amplitude. The Cloud-mode destination doesn't track sessions by default. Use the Browser SDK as a shell to manage sessions, and use Session Replay as a plugin, as shown in the following example.

```javascript
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
import { AnalyticsBrowser } from "@segment/analytics-next";

const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: "segment-key",
});

// A plugin must be added so that events sent through Segment will have
// session replay properties and the correct session id
const segmentPlugin = () => {
  return {
    name: "segment",
    type: "destination",
    execute: async (event) => {
      const properties = event.event_properties || {};
      segmentAnalytics.track(event.event_type, properties, {
        integrations: {
          Amplitude: {
            session_id: amplitude.getSessionId(),
          },
        },
      });
      return {
        code: 200,
        event: event,
        message: "OK",
      };
    },
  };
}; 

const AMPLITUDE_API_KEY = 'api-key' // must match that saved with Segment

// Add the session replay plugin first, then the segment plugin
await amplitude.add(sessionReplayPlugin()).promise;
await amplitude.add(segmentPlugin()).promise;

const user = await segmentAnalytics.user();
await amplitude.init(AMPLITUDE_API_KEY, { 
  instanceName: 'session-replay',
  sessionTimeout: Number.MAX_SAFE_INTEGER,
  defaultTracking: false,
  deviceId: user.anonymousId()
}).promise;
amplitude.remove('amplitude');
// Events must be tracked through the shell Browser SDK to properly attach
// session replay properties
amplitude.track('event name')
```

## Device ID and session ID character constraints

The session replay ID has the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, the `deviceId` value can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. Segment's `anonymousId()` returns a UUID, which always meets these requirements. If you use a custom value for `deviceId`, ensure it follows the accepted character set. To request an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Troubleshoot Segment integration

If the instance returns empty, your Segment middleware may not have populated the values for the Amplitude integration field `payload.obj.integrations['Actions Amplitude']`. If this happens, add the following `setTimeout` wrapper to ensure the field populates with a valid value.

```js
segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
    const storedSessionId = getStoredSessionId()
    setTimeout(() => { 
      ... // Rest of the Segment integrations code
    }, 0) 
    next(payload)
});
```

================================================================================
# Session Replay iOS Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin
Updated: 2025-03-18
================================================================================

# Session Replay iOS Plugin

- **Package:** `AmplitudeSessionReplay` ([cocoapods](https://cocoapods.org/pods/AmplitudeSessionReplay))
- **Latest version:** 0.12.8

This article covers how to install Session Replay using the iOS plugin. If your app already uses the Amplitude [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) or legacy Amplitude [iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk), use this option.

If you use Segment through their Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration).

If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk).

> **Info:** Unified SDK
>
> Install the [Unified SDK for Swift](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk) to access Session Replay along with other Amplitude products (Analytics, Experiment). The Unified SDK provides a single entry point for all Amplitude features and simplifies integration by handling initialization and configuration of all components.

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

Session Replay captures changes to an app's view tree, including the main view and all its child views recursively. Session Replay then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each view change as a diff. When you watch the replay of a session, Session Replay applies each diff back to the original view tree in sequential order to construct the replay. Session replays have no maximum length.

> **Tip:** Report issues
>
> To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).

## Before you begin

The method you use depends on the version of the Amplitude iOS SDK you use.

#### iOS Swift SDK

The Session Replay iOS Plugin requires that:

1. Your application runs on iOS or iPadOS.
2. You use `1.9.0` or higher of the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk).

#### iOS SDK (maintenance)

The Session Replay Middleware requires that:

1. Your application runs on iOS or iPadOS.
2. You use `8.22.0` or higher of the [(maintenance) Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk).
3. You can provide a device ID to the SDK.

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the plugin to your project dependencies.

#### Swift SDK

**Swift Package Manager**

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.12.8")
]
```

For integrating with `Amplitude-Swift`, use the `AmplitudeSwiftSessionReplayPlugin` target.

```swift
.product(name: "AmplitudeSwiftSessionReplayPlugin", package: "AmplitudeSessionReplay")
```

**CocoaPods**

Add the core library and the plugin to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
pod 'AmplitudeSwiftSessionReplayPlugin', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
```

**Configure your application code**

```swift
import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin

// Initialize Amplitude Analytics SDK instance
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY))

// Create and Install Session Replay Plugin
// Recording will be handled automatically
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0))
```

#### Legacy SDK

**Swift Package Manager**

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.12.8")
]
```

For integrating with `Amplitude-iOS`, use the `AmplitudeiOSSessionReplayMiddleware` target.

```swift
.product(name: "AmplitudeiOSSessionReplayMiddleware", package: "AmplitudeSessionReplay")
```

**CocoaPods**

Add the core library and the middleware to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
pod 'AmplitudeiOSSessionReplayMiddleware', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
```

**Configure your application code**

```swift
import Amplitude
import AmplitudeiOSSessionReplayMiddleware

// Initialize Amplitude Analytics SDK instance

let amplitude = Amplitude.instance()

// Although not required, we recommend enabling session start and end events when enabling Session Replay
amplitude.defaultTracking.sessions = true

// Create and Install Session Replay Middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1))

amplitude.initializeApiKey(API_KEY)
```

## Configuration

Pass the following option when you initialize the Session Replay plugin:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `Float` | No | `0` | Controls how many sessions Amplitude selects for replay collection. The value 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. |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration ](#remote-configuration) for this instance of Session Replay. |
| `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Sets the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Sets the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). |

### Custom session IDs

Session Replay for iOS version 0.11.2 and later supports string session IDs, for example UUIDs, through the `customSessionId` property. Use a custom session ID if your project defines sessions with a custom event property instead of the Amplitude `session_id`.

When you set `customSessionId`, the value takes precedence over the session ID that the plugin syncs from the Amplitude SDK. Set the property to `nil` to resume using the Amplitude session ID.

```swift
// Keep a reference to the plugin to set the custom session ID
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0)
sessionReplayPlugin.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
amplitude.add(plugin: sessionReplayPlugin)

// Whenever your custom session changes
sessionReplayPlugin.customSessionId = NEW_CUSTOM_SESSION_ID
```

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Change masking at runtime

Set `privacyConfig` on the plugin to change the automatic masking level while the app runs. Set it before or after you add the plugin to Amplitude.

```swift
sessionReplayPlugin.privacyConfig = PrivacyConfig(maskLevel: .conservative)
```

If Remote Config supplies a masking level, it takes precedence. The plugin retains the local `privacyConfig` value and applies it when Remote Config doesn't supply a masking level or when you disable Remote Config.

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

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

```swift
// Set optOut on the Amplitude SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY,
                                                           optOut: true,
                                                           /* other configuration */))
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */))
```

### 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:

```swift
// Set serverZone on the Amplitude SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY,
                                                           serverZone: .EU,
                                                           /* other configuration */))
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */))
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```swift
// This configuration samples 1% of all sessions
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.01))
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones).

```swift
// Use automatic profile selection based on device
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 0.1,
    quality: .automatic
))

// Or set a fixed profile (low, medium, or high)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 0.1,
    quality: .medium
))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device is on a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
// Set uploadConfig through the plugin's Config initializer
let config = AmplitudeSwiftSessionReplayPlugin.Config(
    sampleRate: 0.1,
    uploadConfig: UploadConfig(disableMeteredUploads: true)
)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(config: config))
```

### Disable replay collection

After you enable Session Replay, it runs on your app until either:

- The user leaves your app.
- You call `sessionReplayPlugin.stop()`.
- You remove the plugin from the SDK with `amplitude.remove(plugin: sessionReplayPlugin)`.

Call `sessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> This requires keeping a reference to the SessionReplayPlugin instance `let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(/* session replay options */)`.

Call `sessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the plugin once, without starting capture
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0, autoStart: false)
amplitude.add(plugin: sessionReplayPlugin)

// Start capture when the user enters a screen you want to record
sessionReplayPlugin.start()

// Stop capture when the user leaves that screen
sessionReplayPlugin.stop()
```

You can also use a feature-flag product such as [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria such as location. For example, you can create a feature flag that targets a specific user group, and add that to your initialization logic:

```swift
import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin

// Your existing initialization logic with Amplitude-Swift SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY,
                                                           /* other configuration */))

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.1)
  amplitude.add(plugin: sessionReplayPlugin)
}
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

================================================================================
# Session Replay iOS Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk
Updated: 2025-03-18
================================================================================

# Session Replay iOS Standalone SDK

- **Package:** `AmplitudeSessionReplay` ([cocoapods](https://cocoapods.org/pods/AmplitudeSessionReplay))
- **Latest version:** 0.12.8

This article covers how to install Session Replay for iOS using the standalone SDK. Choose this option if you use a provider other than Amplitude for in-product analytics.

If your app already uses an [Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), use the [Session Replay iOS SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin) instead.

If you use Segment through the Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

> **Tip:** Report issues
>
> To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).

## Before you begin

The Session Replay Standalone SDK requires that:

1. Your application runs on iOS or iPadOS.
2. You track sessions with a timestamp or a custom string session ID that you can pass to the SDK. You inform the SDK whenever the session identifier changes.
3. You can provide a device ID to the SDK.
4. The `Session ID` and `Device ID` you pass to the Standalone SDK match those sent as event properties to Amplitude.

The Standalone SDK doesn't provide session management. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`.

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of Session Replay to your project dependencies.

#### SPM

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.12.8")
]
```

To integrate with third-party analytics, use the `AmplitudeSessionReplay` target.

```swift
.product(name: "AmplitudeSessionReplay", package: "AmplitudeSessionReplay")
```

#### CocoaPods

Add Session Replay to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
```

Configure your application code.

1. Create a `SessionReplay` instance. Pass the API key, and a session identifier and device identifier if available.
2. Call `sessionReplay.start()` to begin capturing replays. The standalone SDK doesn't start capture automatically, so you must call `start()` once you set the device and session identifiers.
3. When the session identifier or device identifier changes, pass the new value to Amplitude with `sessionReplay.sessionId` or `sessionReplay.deviceId`, respectively. For string session IDs, use `sessionReplay.customSessionId` instead. Refer to [Custom session IDs](#custom-session-ids).
4. Collect Session Replay properties to send with other event properties using `sessionReplay.additionalEventProperties`.

```swift
import AmplitudeSessionReplay
import ThirdPartyAnalytics

// Initialize the standalone session replay SDK
let sessionReplay = SessionReplay(apiKey: amplitude.apiKey,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     sampleRate: 0.1)

// Start capturing replays. The standalone SDK doesn't start automatically.
sessionReplay.start()

// Track an event
// Get session replay properties for this session
var eventProperties = event.eventProperties ?? [:]
eventProperties.merge(sessionReplay.additionalEventProperties) { (current, _) in current }
event.eventProperties = eventProperties
ThirdPartyAnalytics.track(event)

// Handle session ID changes
// Whenever the session ID changes
ThirdPartyAnalytics.setSessionId(sessionId)
// Update the session ID in session replay
sessionReplay.sessionId = ThirdPartyAnalytics.getSessionId()

// Handle device ID changes
// Whenever the device ID changes
ThirdPartyAnalytics.setDeviceId(deviceId)
// Update the device ID in session replay
sessionReplay.deviceId = ThirdPartyAnalytics.getDeviceId()
```

## Configuration

Pass the following configuration options when you initialize the Session Replay SDK.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `String` | Yes | n/a | Sets the Amplitude API key. |
| `deviceId` | `String` | No | `nil` | Sets an identifier for the device running your application. Set it before `start()` to associate replay data with the device. |
| `sessionId` | `Int64` | No | `-1` | Sets an identifier for the user's current session. Set it before `start()` to associate replay data with the session. The value must use milliseconds since epoch (Unix timestamp). To use a string session ID instead, set the `customSessionId` property after initialization. Refer to [Custom session IDs](#custom-session-ids). |
| `sampleRate` | `Float` | No | `0` | Controls how many sessions to select for replay collection. Use a decimal between 0 and 1, for example `0.4`, to set the fraction of sessions Amplitude randomly selects. Over a large number of sessions, `0.4` selects 40% of those sessions. |
| `optOut` | `Bool` | No | `false` | Sets permission to collect replays for sessions. A value of `true` prevents Amplitude from collecting session replays. |
| `logger` | `CoreLogger?` | No | `nil` | Sets a custom logger to emit log messages to a destination you choose. When `nil`, Session Replay logs errors through an OS logger. |
| `serverZone` | `ServerZone` | No | `.US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in the EU data center. |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Configures the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Configures the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). |

### Custom session IDs

Session Replay for iOS version 0.11.2 and later supports string session IDs, for example UUIDs, through the `customSessionId` property. Use a custom session ID if your project defines sessions with a custom event property instead of a timestamp-based `session_id`.

The initializer accepts only a numeric `sessionId`. To use a string value, set `customSessionId` on the instance after you create it, and update it whenever your custom session changes:

```swift
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sampleRate: 0.1)

// Set a string session ID instead of the numeric sessionId
sessionReplay.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
sessionReplay.start()

// Whenever your custom session changes
sessionReplay.customSessionId = ThirdPartyAnalytics.getCustomSessionId()
```

`sessionId` and `customSessionId` are two views of the same underlying value, which the SDK stores as a string:

- Setting `sessionId` replaces the current custom session ID with the numeric value. When you use custom session IDs, update `customSessionId` instead of `sessionId` whenever the session changes.
- When the stored value isn't numeric, the `sessionId` property returns `-1`. Read `customSessionId` to get the current value.
- Setting a different value ends the current replay and starts a new one.

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Change masking at runtime

Set `privacyConfig` to change the automatic masking level while the app runs.

```swift
sessionReplay.privacyConfig = PrivacyConfig(maskLevel: .conservative)
```

If Remote Config supplies a masking level, it takes precedence. The SDK retains the local `privacyConfig` value and applies it when Remote Config doesn't supply a masking level or when you disable Remote Config.

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

Session Replay provides an opt-out configuration option. Passing `optOut: true` during initialization prevents Amplitude from collecting session replays. For example:

```swift
// Pass a boolean value to indicate a user's opt-out status
        let sessionReplay = SessionReplay(apiKey: API_KEY,
                                             optOut: true,
                                             /* other session replay options */)
```

### 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:

```swift
// Set serverZone to EU
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     serverZone: .EU,
                                     /* other session replay options */)
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```swift
// This configuration samples 1% of all sessions
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     sampleRate: 0.01,
                                     /* other session replay options */)
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and image resolution. Higher profiles use a higher frame rate and resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones).

```swift
// Use automatic profile selection based on device
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     quality: .automatic,
                                     /* other session replay options */)

// Or set a fixed profile (low, medium, or high)
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     quality: .medium,
                                     /* other session replay options */)
```

You can also change the profile for an existing standalone instance:

```swift
sessionReplay.quality = .medium
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device uses a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     uploadConfig: UploadConfig(disableMeteredUploads: true),
                                     /* other session replay options */)
```

### Disable replay collection

After you enable Session Replay, it runs on your app until either:

- The user leaves your app.
- You call `sessionReplay.stop()`.

Call `sessionReplay.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

Call `sessionReplay.start()` to re-enable replay collection when the user returns to an unrestricted area of your app. Because `start()` and `stop()` resume and pause capture on the same instance, you can call them on screen transitions to record only the screens you choose.

### Flush recorded data

Call `flush()` to ask the standalone SDK to flush recorded replay data. This is useful when your host analytics client flushes and you want to flush Session Replay at the same point.

```swift
sessionReplay.flush()
```

You can also use a feature flag product like [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, and add it to your initialization logic:

```swift
import AmplitudeSessionReplay
import ThirdPartyAnalytics

let sessionReplay = SessionReplay(apiKey: amplitude.apiKey,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     sampleRate: 1.0)

if (nonEUCountryFlagEnabled) {
    sessionReplay.start()
}
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

## Troubleshooting

For more information about individual statuses and errors, see the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

### Multiple Amplitude instances

Session Replay supports attaching to a single instance of the Amplitude SDK. If you have more than one instance instrumented in your application, make sure to start Session Replay on the instance that most relates to your project.

### Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This happens when a user closes the `[Amplitude] End Session` occurs, but before the iOS SDK and Session Replay middleware can process it. When the user uses the app again, the SDK and middleware process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

### Session replays don't appear in Amplitude

Session replays may not appear in Amplitude due to:

- Lack of connectivity
- No events triggered through the iOS SDK in the current session
- Sampling

#### Lack of connectivity

Ensure your app has access to the internet then try again.

#### No events triggered through the iOS SDK in the current session

Session Replay requires that at least one event in the user's session has the `[Amplitude] Session Replay ID` property. If you instrument your events with an analytics provider other than Amplitude, the iOS SDK may send only the default Session Start and Session End events, which don't include this property.

For local testing, you can force a Session Start event to ensure that Session Replay functions.

1. In Amplitude, in the User Lookup Event Stream, you should see a Session Start event that includes the `[Amplitude] Session Replay ID` property. After processing, the Play Session button should appear for that session.

#### Sampling

As mentioned above, the default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information see, [Sampling rate](#sampling-rate).

#### Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the `[Amplitude] Session Replay ID` property, only that one event in the session has it. Reasons why `[Amplitude] Session Replay ID`  may not be present in an event include:

- The user may have opted out or the session may not be part of the sample set given the current `sampleRate`. Increasing the `sampleRate` captures more sessions.
- Amplitude events may still send through your provider, but `additionalEventProperties` doesn't return the `[Amplitude] Session Replay ID` property. This can result from `optOut` and `sampleRate` configuration settings. Check that `optOut` and `sampleRate` are set to include the session.

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may be the result of one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a users bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

### Report an Issue

If you encounter any issues with Session Replay that aren't covered in the troubleshooting guide above, please report them on our [GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-iOS).

When creating an issue, please include:

- A clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- SDK version you're using
- Any relevant error messages or logs

================================================================================
# Session Replay iOS Segment Integration
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration
Updated: 2025-03-18
================================================================================

# Session Replay iOS Segment Integration

This article covers installation of Session Replay using the Session Replay iOS Segment plugin. Use this option if your app uses Segment's Analytics-Swift library and Amplitude (Actions) destination.

If your app uses an [Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), use the [Session Replay iOS SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin).

If you use Segment with other options, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

Session Replay captures changes to an app's view tree: the main view and all its child views recursively. Session Replay then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each change as a diff. When you watch the replay, Session Replay applies each diff back to the original view tree in sequential order. Session replays have no maximum length.

> **Tip:** Report issues
>
> To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).

## Before you begin

The Session Replay iOS Segment Plugin requires that:

1. Your application runs on iOS or iPadOS.
2. You use Segment's Analytics-Swift library for ingestion.
3. You use Segment's Amplitude (Actions) destination.
4. You use Segment's [Amplitude Plugin](https://segment.com/docs/connections/sources/catalog/libraries/mobile/apple/destination-plugins/amplitude-swift/).

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the plugin to your project dependencies.

The Segment plugin is available through Swift Package Manager only. Add Session Replay as a dependency in your Package.swift file or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.12.8")
]
```

To integrate with `Analytics-Swift`, use the `AmplitudeSegmentSessionReplayPlugin` target.

```swift
.product(name: "AmplitudeSegmentSessionReplayPlugin", package: "AmplitudeSessionReplay")
```

Configure your application code:

```swift
import AmplitudeSegmentSessionReplayPlugin
import Segment
import SegmentAmplitude

// Initialize Segment
let analytics = Analytics(configuration: config)

// Ensure Segment's AmplitudeSession plugin is added before AmplitudeSegmentSessionReplayPlugin
analytics.add(plugin: AmplitudeSession())

// Initialize AmplitudeSegmentSessionReplayPlugin with your Amplitude API key
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1))
```

## Configuration

Pass the following option when you initialize the Session Replay plugin:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `amplitudeApiKey` | `String` | Yes | n/a | Sets the Amplitude API key. The Segment plugin requires this value to send replays to Amplitude. |
| `sampleRate` | `Float` | No | `0` | Use this option to control how many sessions to select for replay collection. The number should be a decimal between 0 and 1 (for example, `0.4`), representing the fraction of sessions to have randomly selected for replay collection. Over a large number of sessions, `0.4` would select `40%` of those sessions. |
| `serverZone` | `ServerZone` | No | `.US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in EU data center. |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration ](#remote-configuration) for this instance of Session Replay. |
| `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Use this option to configure the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Use this option to configure the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). |

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> When you enable remote configuration, settings you define in Amplitude take precedence over settings you define locally in the SDK. As a result, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

Set `optOut` on the plugin to indicate that a user opted out of session replay.

```swift
// Pass a boolean value to indicate a users opt-out status
amplitudeSegmentSessionReplayPlugin.optOut = true
```

### 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:

```swift
// Set serverZone on the AmplitudeSegmentSessionReplayPlugin
let plugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                     sampleRate: 0.1,
                                                     serverZone: .EU)
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```swift
// This configuration samples 1% of all sessions
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.01))
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device. For example, the SDK selects high on newer devices and lower on older ones.

```swift
// Use automatic profile selection based on device
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1,
                                                              quality: .automatic))

// Or set a fixed profile (low, medium, or high)
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1,
                                                              quality: .medium))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device uses a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1,
                                                              uploadConfig: UploadConfig(disableMeteredUploads: true)))
```

### Disable replay collection

After you enable Session Replay, it runs on your app until either:

- The user leaves your app.
- You call `amplitudeSegmentSessionReplayPlugin.stop()`.
- You remove the plugin from Segment with `analytics.remove(plugin: amplitudeSegmentSessionReplayPlugin)`.

Call `amplitudeSegmentSessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> Keep a reference to the SessionReplayPlugin instance: `let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(/* session replay options */)`.

Call `amplitudeSegmentSessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the plugin once, without starting capture
let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                                              sampleRate: 1.0,
                                                                              autoStart: false)
analytics.add(plugin: amplitudeSegmentSessionReplayPlugin)

// Start capture when the user enters a screen you want to record
amplitudeSegmentSessionReplayPlugin.start()

// Stop capture when the user leaves that screen
amplitudeSegmentSessionReplayPlugin.stop()
```

You can also use a feature flag product like [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, then add that flag to your initialization logic:

```swift
import AmplitudeSegmentSessionReplayPlugin
import Segment
import SegmentAmplitude

// Your existing initialization logic with Segment
let analytics = Analytics(configuration: config)
analytics.add(plugin: AmplitudeSession())

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY, sampleRate: 0.1)
  analytics.add(plugin: amplitudeSegmentSessionReplayPlugin)
}
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

================================================================================
# Session Replay iOS Middleware
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-middleware
Updated: 2025-03-18
================================================================================

# Session Replay iOS Middleware

> **Alpha:** Early access SDK
>
> As an Alpha release, this SDK may contain bugs and cause crashes. Before you enable in production, thoroughly test your app in a controlled environment. For more information about best practices for developer preview SDKs, see [SDK Maintenance and Support](https://amplitude.com/docs/sdks/sdk-maintenance-and-support#sdk-major-version-life-cycle).

This article covers Session Replay installation through the [iOS SDK middleware](https://amplitude.com/docs/sdks/sdk-middleware). If your app already uses the [(maintenance) Amplitude SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk), use this option.

If your app already uses the [(latest) iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), choose the [Session Replay iOS SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin).

If you use Segment through their Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration).

If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

## Before you begin

The Session Replay Middleware requires that:

1. Your application runs on iOS or iPadOS.
2. You use `8.22.0` or higher of the [(maintenance) Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk).
3. You can provide a device ID to the SDK.

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the middleware to your project dependencies.

#### SPM

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.12.8")
]
```

For integrating with `Amplitude-iOS`, use the `AmplitudeiOSSessionReplayMiddleware` target.

```swift
.product(name: "AmplitudeiOSSessionReplayMiddleware", package: "AmplitudeSessionReplay")
```

#### CocoaPods

Add the core library and the middleware to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
pod 'AmplitudeiOSSessionReplayMiddleware', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
```

Configure your application code:

```swift
import Amplitude
import AmplitudeiOSSessionReplayMiddleware

// Initialize Amplitude Analytics SDK instance

let amplitude = Amplitude.instance()

// Although not required, we recommend enabling session start and end events when enabling Session Replay
amplitude.defaultTracking.sessions = true

// Create and Install Session Replay Middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1))

amplitude.initializeApiKey(API_KEY)
```

## Configuration

Pass the following options when you initialize the Session Replay middleware:

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `Float` | No | `0` | Controls how many sessions to select for replay collection. Use a decimal between 0 and 1, for example `0.4`, representing the fraction of sessions randomly selected for replay collection. Over a large number of sessions, `0.4` selects `40%` of those sessions. For more information, refer to [Sampling rate](#sampling-rate). |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables remote configuration for this instance of Session Replay. |
| `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Sets the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Sets the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). |

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

The Session Replay middleware follows the Amplitude-iOS SDK's `optOut` setting and doesn't support user opt-outs on its own.

```swift
// Set optOut on the Amplitude SDK
amplitude.optOut = true
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */))
```

### 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:

```swift
// Set serverZone on the Amplitude SDK
amplitude.setServerZone(.EU)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */))
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```swift
// This configuration samples 1% of all sessions
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.01))
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones).

```swift
// Use automatic profile selection based on device
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
    sampleRate: 0.1,
    quality: .automatic
))

// Or set a fixed profile (low, medium, or high)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
    sampleRate: 0.1,
    quality: .medium
))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device is on a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
    sampleRate: 0.1,
    uploadConfig: UploadConfig(disableMeteredUploads: true)
))
```

### Disable replay collection

After it's enabled, Session Replay runs on your app until either:

- The user leaves your app.
- You call `sessionReplayMiddleware.stop()`.
- You remove the middleware from the SDK with `amplitude.removeEventMiddleware(sessionReplayMiddleware)`.

Call `sessionReplayMiddleware.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> This requires keeping a reference to the Session Replay Middleware instance `let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(/* session replay options */)`.

Call `sessionReplayMiddleware.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the middleware with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the middleware once, without starting capture
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 1.0, autoStart: false)
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Start capture when the user enters a screen you want to record
sessionReplayMiddleware.start()

// Stop capture when the user leaves that screen
sessionReplayMiddleware.stop()
```

You can also use a feature flag product like [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria like location. For example, you can create a feature flag that targets a specific user group and add that to your initialization logic:

```swift
import Amplitude
import AmplitudeiOSSessionReplayMiddleware

// Your existing initialization logic with Amplitude-iOS SDK
let amplitude = Amplitude.instance()

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Middleware
  let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1)
  amplitude.addEventMiddleware(sessionReplayMiddleware)
}

amplitude.initializeApiKey(API_KEY)
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

================================================================================
# Session Replay Android Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin
Updated: 2025-03-18
================================================================================

# Session Replay Android Plugin

- **Package:** `com.amplitude:plugin-session-replay-android` ([maven](https://search.maven.org/artifact/com.amplitude/plugin-session-replay-android))
- **Latest version:** 0.29.0

Install Session Replay with the Android SDK plugin when your app is already instrumented with Amplitude. If you use a different provider for in-product analytics, use the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone) instead.

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the Android apps in which it's installed by:
>
> - Asynchronously capturing and processing replay data, to avoid blocking the main user interface thread. The main thread must analyze the view hierarchy, but snapshot capture scheduling and extra processing offloads to the background.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

Session Replay captures changes to an app's view tree. The view tree includes the main view and all child views recursively. Session Replay then replays these changes to build a video-like replay.

For example, at the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each change to the view as a diff. Session Replay then constructs the replay of the session by applying each diff to the original view tree in sequential order.

Session replays have no maximum length.

> **Tip:** Report issues
>
> To report issues with Session Replay for Android, go to the [AmplitudeSessionReplay-Android GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

## Before you begin

The method you use depends on the version of the Amplitude Android SDK you use.

#### Android-Kotlin

If you use the current [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), follow the instructions for the Android Plugin.

The Session Replay Android plugin requires that:

1. Your application is Android-based.
2. You can provide a device identifier to the SDK.

#### Android (maintenance)

If you use the [maintenance Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk), use the instructions for Android Middleware.

The Session Replay Middleware requires that:

1. Your application is Android-based.
2. You use `2.40.1` or higher of the [(maintenance) Amplitude Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk).
3. You can provide a device ID to the SDK.

### Supported Android versions

Session replay supports down to Android 5.0 with a minimum SDK of 21 `minSdk = 21`. This should support over 99.6% of global Android devices according to Google's distribution data in Android Studio.

## Quickstart

#### Kotlin SDK

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/plugin-session-replay-android/versions) of the plugin to your project dependencies.

```kotlin
// Install latest version from Maven Central
implementation("com.amplitude:plugin-session-replay-android:0.29.0")
// You will also need the Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:analytics-android:[1.29.0,2.0.0)")
```

Configure your application code:

```kotlin
import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.android.plugins.SessionReplayPlugin

// Initialize Amplitude Analytics SDK instance
val amplitude = Amplitude(
    Configuration(
        apiKey = API_KEY,
        context = applicationContext
    )
)

// Create and Install Session Replay Plugin
// Recording will be handled automatically
val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 1.0)
amplitude.add(sessionReplayPlugin)
```

#### Legacy SDK

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/middleware-session-replay-android/versions) of the session replay middleware to your project dependencies.

```kotlin
// Install latest version from Maven Central
implementation("com.amplitude:middleware-session-replay-android:0.26.1")
// You will also need the (maintenance) Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:android-sdk:[2.40.1,3.0.0)")
```

Configure your application code.

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Initialize (maintenance) Amplitude Analytics SDK instance
val amplitude = Amplitude.getInstance()
    .initialize(this, AMPLITUDE_API_KEY)
    // Replay events will be flushed on close as well
    // If setFlushEventsOnClose(false) you must call flush() manually
    .setFlushEventsOnClose(true)

// Create Session Replay Middleware
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0)

// Add session replay middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Track events
amplitude.logEvent("Setup (maintenance) Amplitude Android SDK with session replay!")

// Send replay events to the server
amplitude.uploadEvents()

// You can also call flush() on the middleware directly to only send replay events
// sessionReplayMiddleware.flush()

// Always flush before app exit (onPause)
// override fun Activity.onPause() { sessionReplayMiddleware.flush() }
```

> **Info:** Sample rate
>
> The sample rate in these code samples is `1.0`. This setting ensures Amplitude captures sessions during testing, but can cause overages in production.

## Configuration

Pass the following options when you initialize the Session Replay plugin.

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `Number` | No | `0.0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, which selects 40% of sessions over a large number of sessions. |
| `enableRemoteConfig` | `Boolean` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig()` | Privacy settings that control which views Session Replay masks. Set the mask level with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. Refer to [Mask level](#mask-level). |
| `serverUrl` | `String?` | No | `null` | _Advanced._ Explicit server URL, useful for proxy setups. |
| `bandwidthLimitBytes` | `Int?` | No | `null` | _Advanced._ Daily upload limit, in bytes, on metered (for example, cellular) connections. |
| `storageLimitMB` | `Int?` | No | `null` | _Advanced._ Local storage limit, in MB. |
| `autoStart` | `Boolean` | No | `true` | Starts screen capture automatically when the plugin initializes. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Maximum length of a log message. |

### Custom session IDs

Session Replay for Android version 0.26.4 and later supports string session IDs, for example UUIDs, through the `setCustomSessionId` method. Use a custom session ID if your project defines sessions with a custom event property instead of the Amplitude `session_id`.

When you set a custom session ID, the value takes precedence over the session ID that the plugin syncs from the Amplitude SDK. Pass `null` to clear the override and resume using the Amplitude session ID.

```kotlin
// Keep a reference to the plugin to set the custom session ID
val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 1.0)
sessionReplayPlugin.setCustomSessionId("ef197fc7-a46f-4e6c-a77f-8d90c17065c0")
amplitude.add(sessionReplayPlugin)

// Whenever your custom session changes
sessionReplayPlugin.setCustomSessionId(newCustomSessionId)
```

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Mask on-screen data

The Session Replay SDK offers four ways to mask user input, text, and other view components.

#### Mask level

Session Replay for Android supports three levels of masking, set through the `privacyConfig` option with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. The default level is `medium`.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks password, email, and phone number input fields. In SDK `0.26.2` and later, `light` also masks any field with sensitive autofill hints (credit card number, expiration, and security code; name; username; postal address and code); autofill-hint detection requires Android 8.0 (API 26) or higher. Earlier versions, including the `middleware-session-replay-android` artifact, mask only the input-field types above. |
| `medium` (default) | Everything in `light`, plus all editable text fields (`EditText`). |
| `conservative` | Everything in `medium`, plus all text views (`TextView`). |

#### Privacy tags in layout XML

Use this option in your application's layout XML.

| View | Description |
| --- | --- |
| `<EditText>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the tag `amp-unmask`. For example: `<EditText android:tag="amp-unmask" android:text="Unmask this">`. |
| `<TextView>` | To mask text within non-input elements, add the tag `amp-mask`. For example, `<TextView android:tag="amp-mask" android:text="Mask this"/>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the tag `amp-block`. For example, `<ImageView android:tag="amp-block"/>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |
| `<WebView>` | To unmask a web view, add the `amp-unmask` tag. For example, `<WebView android:tag="amp-unmask"/>`. |

#### Privacy methods on the Session Replay SDK

Import the `SessionReplay` class, then call one of the methods below from your application's code.

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
```

| Method | Description |
| --- | --- |
| `unmask(view: View)` | To unmask a view manually, call `SessionReplay.unmask(view)` where `view` is a reference to any view that is masked. |
| `mask(view: View)` | To mask text within non-input views, call `SessionReplay.mask(view)` where `view` is a reference to the any view you want to mask. When masked, Session Replay captures masked text as a series of asterisks. |
| `block(view: View)` | To block a non-text view, call `SessionReplay.block(view)` where `view` is a reference to the View you want to block. Session Replay replaces blocked views with a placeholder of the same dimensions. |

#### Privacy modifiers in Jetpack Compose

For composables, use the privacy modifiers instead of layout XML tags or the `SessionReplay` methods. These modifiers require version `0.21.0` or higher of the Session Replay Android SDK or plugin.

Import the modifier you need from `com.amplitude.android.sessionreplay.compose`, then add it to the composable's modifier chain.

```kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
```

| Modifier | Description |
| --- | --- |
| `Modifier.ampMask()` | Masks text that Session Replay captures by default, such as the contents of a `Text` composable. Session Replay captures masked text as a series of asterisks. |
| `Modifier.ampUnmask()` | Unmasks a composable that Session Replay masks by default, such as a `TextField`. |
| `Modifier.ampBlock()` | Blocks a composable. Session Replay replaces blocked composables with a placeholder of the same dimensions and doesn't capture their contents. |

```kotlin
// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)

// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)

// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}
```

A privacy modifier applies to the composable you add it to and to everything nested inside it. When a nested composable has its own privacy modifier, that modifier takes precedence for that composable and its descendants.

### User opt-out

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

```kotlin
// Set optOut on the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = API_KEY,
    optOut = true,
    /* other configuration */
))
amplitude.add(SessionReplayPlugin(/* session replay options */))
```

### 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:

```kotlin
// Set serverZone on the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = API_KEY,
    serverZone = ServerZone.EU,
    /*, other configuration */
))
amplitude.add(SessionReplayPlugin(/* session replay options */))
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```kotlin
// This configuration samples 1% of all sessions
amplitude.add(SessionReplayPlugin(sampleRate = 0.01))
```

### Disable replay collection

After you enable Session Replay, it runs on your app until either:

- The user leaves your app.
- You call `sessionReplayPlugin.stop()`.
- You remove the plugin from the SDK with `amplitude.remove(sessionReplayPlugin)`.

Call `sessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> This requires keeping a reference to the `SessionReplayPlugin` instance: `val sessionReplayPlugin = SessionReplayPlugin(/* session replay options */)`.

Call `sessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart = false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```kotlin
// Add the plugin without starting capture
val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 1.0, autoStart = false)
amplitude.add(sessionReplayPlugin)

// Start capture when the user enters a screen you want to record
sessionReplayPlugin.start()

// Stop capture when the user leaves that screen
sessionReplayPlugin.stop()
```

You can also use a feature flag product like Amplitude Experiment to enable or disable replay collection based on criteria like location. For example, you can create a feature flag that targets a specific user group, then add it to your initialization logic:

```kotlin
import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.android.plugins.SessionReplayPlugin

// Your existing initialization logic with Android SDK
val amplitude = Amplitude(Configuration(apiKey = API_KEY /*, ... other configuration */))

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 0.5)
  amplitude.add(sessionReplayPlugin)
}
```

### WebView and MapView support (Beta)

By default, Session Replay blocks web views and map views in a capture. To enable capture of these components, use the settings described in [Mask on-screen data](#mask-on-screen-data).

Web view session replay injects JavaScript into the rendered page. To enable this, the SDK sets `javaScriptEnabled` to `true` on the unmasked web view.

### Log Recording

> **Note:** Availability
>
> Log recording is available in Session Replay Android `0.22.0` and later.

Session Replay supports recording logs in Android applications. To enable log recording, send log messages through the `recordLog(level, message, timestamp)` API and configure the limits through `recordLogOptions` parameter while initializing Session Replay.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions

val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)

sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")

// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")
```

Session Replay supports predefined log levels (`Error`, `Warn`, `Log`) and custom log levels. Create custom log levels by passing any string value to `RecordLogLevel(...)`.

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### Timber

If you use `Timber`, you can integrate it with a custom tree.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber

class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}

val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)

Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

- Memory usage grows until you call `flush()` to transfer the session replay data to the server.
- Session data isn't retried on failure to transfer to the Amplitude servers.

Amplitude recommends setting `flushEventsOnClose = true` in the Amplitude SDK Configuration (the default) to send session data to the server on each app exit.

## Jetpack Compose Support (Alpha)

Session Replay supports Jetpack Compose for Android applications. This feature is currently in Alpha. To use Jetpack Compose with Session Replay, ensure you use version `0.20.4` or higher of the Session Replay Android SDK or plugin.

To control what Session Replay captures in a composable, use the [privacy modifiers in Jetpack Compose](#privacy-modifiers-in-jetpack-compose). Masking support for Compose requires `0.21.0` or higher.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay can't capture the following Android views:

  - Canvas Views

### Multiple Amplitude instances

Session Replay supports attaching to a single instance of the Amplitude SDK. If you have more than one instance instrumented in your application, start Session Replay on the instance that most relates to your project.

## Troubleshooting

For more information about individual statuses and errors, see the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).                                                                                    |

### Captured sessions contain limited information

Session Replay requires that the Android SDK send at least one event that includes Session Replay ID. If you instrument events outside of the Android SDK, Amplitude doesn't tag those events as part of the session replay. This means you can't use tools like Funnel Analysis, Segmentation, or Journeys charts to find session replays. You can find session replays with the User Sessions chart or through User Lookup.

If you use a method other than the Android SDK to instrument your events, consider using the [Session Replay Standalone SDK for Android](https://amplitude.com/docs/session-replay/session-replay-android-standalone/).

### Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This happens when a user closes the `[Amplitude] End Session` occurs, but before the Android SDK and Session Replay plugin can process it. When the user uses the app again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

### Session replays don't appear in Amplitude

Session replays may not appear in Amplitude due to:

- Lack of connectivity
- Failed to flush recording before exiting the app
- No events triggered through the Android SDK in the current session
- Sampling

#### Lack of connectivity

Ensure your app has access to the internet then try again.

#### No events triggered through the Android SDK in the current session

Session Replay requires that at least one event in the user's session has the `[Amplitude] Session Replay ID` property. If you instrument your events with a method other than the [Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), the Android SDK may send only the default Session Start and Session End events, which don't include this property.

For local testing, you can force a Session Start event to ensure that Session Replay functions.

1. In Amplitude, in the User Lookup Event Stream, you should see a Session Start event that includes the `[Amplitude] Session Replay ID` property. After processing, the Play Session button should appear for that session.

#### Sampling

As mentioned above, the default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information see, [Sampling rate](#sampling-rate).

#### Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the `[Amplitude] Session Replay ID` property, only that one event in the session has it. Reasons why `[Amplitude] Session Replay ID`  may not be present in an event include:

- The user may have opted out or may not be part of the sample set given the current `sampleRate`. Increasing the `sampleRate` captures more sessions.
- Amplitude events may still send through your provider, but `getSessionReplayProperties()` doesn't return the `[Amplitude] Session Replay ID` property. This can result from `optOut` and `sampleRate` configuration settings. Check that `optOut` and `sampleRate` are set to include the session.

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may be the result of one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a users bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If Session Replay isn't implemented on all pages a user visits, their session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

### Report an Issue

If you encounter any issues with Session Replay that aren't covered in the troubleshooting guide above, please report them on our [GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

When creating an issue, please include:

- A clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- SDK version you're using
- Any relevant error messages or logs

### Captured sessions contain limited information

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. If you don't see this event in your implementation, replays may not appear correctly in Amplitude's analysis tools like Funnel Analysis, Segmentation, or Journeys charts. You can still find session replays on the Session Replay home page or the user profile page.

Reasons this event may not appear include:

- The user opted out or isn't part of the sample set given the current `sampleRate`. Increase the `sampleRate` to capture more sessions.
- You enabled the `optOut` configuration for the session. Check that `optOut` and `sampleRate` settings include the session.
- Your app uses a method other than the Android SDK to instrument events. Consider using the [Session Replay Standalone SDK for Android](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone/).

If you verify these settings and still don't see the event, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

### Replay length and session length don't match

In some scenarios, the length of a replay can exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This situation happens when a user closes the app after the `[Amplitude] End Session` event occurs, but before the Android SDK and Session Replay plugin can process the event. When the user uses the app again, the SDK and plugin process the event and send it to Amplitude with the replay. To verify this scenario, check for a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

### Session replays don't appear in Amplitude

Session replays may not appear in Amplitude for these reasons:

- Lack of connectivity. Ensure your app has access to the internet, then try again.
- Failure to flush the recording before exiting the app.
- No events sent through the Android SDK in the current session.
- Missing `[Amplitude] Replay Captured` event. Review [Captured sessions contain limited information](#captured-sessions-contain-limited-information).
- Sampling.

#### Sampling

The default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information, refer to [Sampling rate](#sampling-rate).

### Session Replay processing errors

Replays should be available within minutes of ingestion. Delays or errors may result from one or more of the following:

- Mismatching API keys or Device IDs. This mismatch happens when Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a user closes the app within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If you haven't implemented Session Replay on all pages a user visits, the session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

================================================================================
# Session Replay Android Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone
Updated: 2025-03-18
================================================================================

# Session Replay Android Standalone SDK

- **Package:** `com.amplitude:session-replay-android` ([maven](https://search.maven.org/artifact/com.amplitude/session-replay-android))
- **Latest version:** 0.29.0

This article covers how to install Session Replay for Android with the standalone SDK. If you use a provider other than Amplitude for in-product analytics, choose this option. If your app already uses the Amplitude Android SDK, use the [Session Replay Android SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin) instead.

> **Tip:** Report issues
>
> To report issues with Session Replay for Android, go to the [AmplitudeSessionReplay-Android GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the Android apps in which it's installed by:
>
> - Asynchronously capturing and processing replay data, to avoid blocking the main user interface thread. The main thread must analyze the view hierarchy, but snapshot capture scheduling and extra processing offloads to the background.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

## Before you begin

The Session Replay Standalone SDK requires that:

1. Your application is Android-based.
2. You track sessions with a timestamp or a custom string session ID that you can pass to the SDK. Inform the SDK whenever the session identifier changes.
3. You can provide a device ID to the SDK.
4. The `Session ID` and `Device ID` you pass to the Standalone SDK match those sent as event properties to Amplitude.

The Standalone SDK doesn't provide session management capabilities. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`.

### Supported Android versions

Session replay supports down to Android 5.0 with a minimum SDK of 21 `minSdk = 21`. This should support over 99.6% of global Android devices according to Google's distribution data in Android Studio.

## Quickstart

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/session-replay-android/versions) of the Session Replay SDK to your project dependencies.

```kotlin
implementation("com.amplitude:session-replay-android:0.29.0")
```

Configure your application code:

1. Create a `val sessionReplay = SessionReplay()` object to start collecting replays. Pass the API key, session identifier, and device identifier.
2. When the session or device identifier changes, pass the new value to Amplitude with `sessionReplay.setSessionId` or `sessionReplay.setDeviceId`. For string session IDs, use `sessionReplay.setCustomSessionId` instead. Refer to [Custom session IDs](#custom-session-ids).
3. Call `sessionReplay.flush` to send session replay data to Amplitude. Always call `flush` before the app exits or moves to the background. For longer sessions, call `flush` often to prevent high memory use (alpha).

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
import com.example.ThirdPartyAnalytics

// Initialize the standalone session replay SDK
val sessionReplay = SessionReplay(
    apiKey = "api-key",
    context = applicationContext,
    deviceId = "device-id",
    sessionId = Date().time,
    sampleRate = 1.0,
)

// Handle session ID change
// Whenever the session ID changes
ThirdPartyAnalytics.setSessionId(sessionId)
// Update the session ID in session replay
sessionReplay.setSessionId(ThirdPartyAnalytics.getSessionId())

// Handle device ID change
// When the device ID changes
ThirdPartyAnalytics.setDeviceId(deviceId)
//Update the device ID in session replay
sessionReplay.setDeviceId(ThirdPartyAnalytics.getDeviceId())


// Send session replay data to the server
// This should always be called before app exit
sessionReplay.flush()
```

## Configuration

Pass the following configuration options when you initialize the Session Replay SDK.

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `String` | Yes | n/a | Your Amplitude API key. |
| `context` | `Context` | Yes | n/a | The Android application context. |
| `deviceId` | `String` | Yes | n/a | Identifier for the device running your application. |
| `sessionId` | `Long` | Yes | n/a | Identifier for the user's current session, in milliseconds since epoch (Unix timestamp). To use a string session ID instead, pass `-1` and call `setCustomSessionId` after initialization. Refer to [Custom session IDs](#custom-session-ids). |
| `sampleRate` | `Number` | No | `0.0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, which selects 40% of sessions over a large number of sessions. |
| `optOut` | `Boolean` | No | `false` | Sets permission to collect replays. A value of `true` prevents Amplitude from collecting session replays. |
| `logger` | `Logger` | No | `LogcatLogger` | Sets a custom logger to emit log messages to a destination. Set to `null` to disable logging. |
| `enableRemoteConfig` | `Boolean` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. |
| `serverZone` | `ServerZone` | No | `ServerZone.US` | `ServerZone.EU` or `ServerZone.US`. Set this to EU for Amplitude projects created in the EU data center. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig()` | Privacy settings that control which views are masked. Set the mask level with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. See [Mask level](#mask-level). |
| `serverUrl` | `String?` | No | `null` | _Advanced._ Explicit server URL, useful for proxy setups. |
| `bandwidthLimitBytes` | `Int?` | No | `null` | _Advanced._ Daily upload limit, in bytes, on metered (for example, cellular) connections. |
| `storageLimitMB` | `Int?` | No | `null` | _Advanced._ Local storage limit, in MB. |
| `autoStart` | `Boolean` | No | `true` | Starts screen capture automatically when Session Replay initializes. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Maximum length of a log message. |

### Custom session IDs

Session Replay for Android version 0.26.4 and later supports string session IDs, for example UUIDs, through the `setCustomSessionId` method. Use a custom session ID if your project defines sessions with a custom event property instead of a timestamp-based `session_id`.

The constructor accepts only a numeric `sessionId`. To use a string value, pass `-1` as the `sessionId`, then call `setCustomSessionId`. Session Replay doesn't capture until you set a valid session ID.

```kotlin
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    context = applicationContext,
    deviceId = "device-id",
    sessionId = -1,
    sampleRate = 1.0,
)

// Set a string session ID instead of the numeric sessionId
sessionReplay.setCustomSessionId("ef197fc7-a46f-4e6c-a77f-8d90c17065c0")

// Whenever your custom session changes
sessionReplay.setCustomSessionId(ThirdPartyAnalytics.getCustomSessionId())
```

The numeric `sessionId` and the custom session ID are two views of the same underlying value, which the SDK stores as a string:

- Calling `setSessionId` replaces the current custom session ID with the numeric value. When you use custom session IDs, call `setCustomSessionId` instead of `setSessionId` whenever the session changes.
- When the stored value isn't numeric, `getSessionId` returns `-1`. Call `getCustomSessionId` to read the current value.
- Setting a different value ends the current replay and starts a new one.

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Mask on-screen data

The Session Replay SDK offers four ways to mask user input, text, and other view components.

#### Mask level

Session Replay for Android supports three levels of masking, set through the `privacyConfig` option with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. The default level is `medium`.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks password, email, and phone number input fields. In SDK `0.26.2` and later, `light` also masks any field with sensitive autofill hints (credit card number, expiration, and security code; name; username; postal address and code); autofill-hint detection requires Android 8.0 (API 26) or higher. Earlier versions, including the `middleware-session-replay-android` artifact, mask only the input-field types above. |
| `medium` (default) | Everything in `light`, plus all editable text fields (`EditText`). |
| `conservative` | Everything in `medium`, plus all text views (`TextView`). |

#### Privacy tags in layout XML

Use this option in your application's layout XML.

| View | Description |
| --- | --- |
| `<EditText>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the tag `amp-unmask`. For example: `<EditText android:tag="amp-unmask" android:text="Unmask this">`. |
| `<TextView>` | To mask text within non-input elements, add the tag `amp-mask`. For example, `<TextView android:tag="amp-mask" android:text="Mask this"/>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the tag `amp-block`. For example, `<ImageView android:tag="amp-block"/>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |
| `<WebView>` | To unmask a web view, add the `amp-unmask` tag. For example, `<WebView android:tag="amp-unmask"/>`. |

#### Privacy methods on the Session Replay SDK

Import the `SessionReplay` class, then call one of the methods below from your application's code.

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
```

| Method | Description |
| --- | --- |
| `unmask(view: View)` | To unmask a view manually, call `SessionReplay.unmask(view)` where `view` is a reference to any view that is masked. |
| `mask(view: View)` | To mask text within non-input views, call `SessionReplay.mask(view)` where `view` is a reference to the any view you want to mask. When masked, Session Replay captures masked text as a series of asterisks. |
| `block(view: View)` | To block a non-text view, call `SessionReplay.block(view)` where `view` is a reference to the View you want to block. Session Replay replaces blocked views with a placeholder of the same dimensions. |

#### Privacy modifiers in Jetpack Compose

For composables, use the privacy modifiers instead of layout XML tags or the `SessionReplay` methods. These modifiers require version `0.21.0` or higher of the Session Replay Android SDK or plugin.

Import the modifier you need from `com.amplitude.android.sessionreplay.compose`, then add it to the composable's modifier chain.

```kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
```

| Modifier | Description |
| --- | --- |
| `Modifier.ampMask()` | Masks text that Session Replay captures by default, such as the contents of a `Text` composable. Session Replay captures masked text as a series of asterisks. |
| `Modifier.ampUnmask()` | Unmasks a composable that Session Replay masks by default, such as a `TextField`. |
| `Modifier.ampBlock()` | Blocks a composable. Session Replay replaces blocked composables with a placeholder of the same dimensions and doesn't capture their contents. |

```kotlin
// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)

// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)

// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}
```

A privacy modifier applies to the composable you add it to and to everything nested inside it. When a nested composable has its own privacy modifier, that modifier takes precedence for that composable and its descendants.

### User opt-out

Session Replay provides an opt-out configuration option. Pass `optOut = true` during initialization to prevent Amplitude from collecting session replays. For example:

```kotlin
// Pass a boolean value to indicate a users opt-out status
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    optOut = true,
    /* other session replay options */
)
```

### 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:

```kotlin
// Set serverZone to EU
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    serverZone = ServerZone.EU,
    /* other session replay options */
)
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```kotlin
// This configuration samples 1% of all sessions
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    sampleRate = 0.01,
    /* other session replay options */
)
```

### Disable replay collection

After Session Replay starts, it runs in your app until either:

- The user leaves your app.
- You call `sessionReplay.stop()`.
- You call `sessionReplay.shutdown()` to tear down the instance.

Call `sessionReplay.stop()` before a user navigates to a restricted area of your app to pause replay collection while the user is in that area. Call `sessionReplay.start()` to resume when they return. Both methods act on the same instance.

To tear down Session Replay completely, call `sessionReplay.shutdown()`, then create a new instance to start again.

To capture only specific screens, initialize Session Replay with `autoStart = false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```kotlin
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    context = applicationContext,
    deviceId = "device-id",
    sessionId = Date().time,
    autoStart = false,
)

// Start capture when the user enters a screen you want to record
sessionReplay.start()

// Stop capture when the user leaves that screen
sessionReplay.stop()
```

You can also use a feature flag product like Amplitude Experiment to create logic that enables or disables replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, then add the flag to your initialization logic:

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
import com.example.ThirdPartyAnalytics

val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    deviceId = "device-id",
    sessionId = Date().time,
    sampleRate = 1.0,
    /* other session replay options */
)
```

### WebView and MapView support (Beta)

By default, Session Replay blocks web views and map views in a capture. To enable capture of these components, use the settings described in [Mask on-screen data](#mask-on-screen-data).

Web view session replay injects JavaScript into the rendered page. To enable this, the SDK sets `javaScriptEnabled` to `true` on the unmasked web view.

### Log Recording

> **Note:** Availability
>
> Log recording is available in Session Replay Android `0.22.0` and later.

Session Replay supports recording logs in Android applications. To enable log recording, send log messages through the `recordLog(level, message, timestamp)` API and configure the limits through `recordLogOptions` parameter while initializing Session Replay.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions

val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)

sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")

// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")
```

Session Replay supports predefined log levels (`Error`, `Warn`, `Log`) and custom log levels. Create custom log levels by passing any string value to `RecordLogLevel(...)`.

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### Timber

If you use `Timber`, you can integrate it with a custom tree.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber

class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}

val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)

Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

- Memory usage grows until you call `flush()` to transfer the session replay data to the server.
- Session data isn't retried on failure to transfer to the Amplitude servers.

## Jetpack Compose Support (Alpha)

Session Replay supports Jetpack Compose for Android applications. This feature is currently in Alpha. To use Jetpack Compose with Session Replay, ensure you use version `0.20.4` or higher of the Session Replay Android SDK or plugin.

To control what Session Replay captures in a composable, use the [privacy modifiers in Jetpack Compose](#privacy-modifiers-in-jetpack-compose). Masking support for Compose requires `0.21.0` or higher.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay can't capture the following Android views:

  - Canvas Views

## Troubleshooting

For more information about individual statuses and errors, see the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).                                                                                    |

### Captured sessions contain limited information

Session Replay requires that the Android SDK send at least one event that includes Session Replay ID. If you instrument events outside of the Android SDK, Amplitude doesn't tag those events as part of the session replay. This means you can't use tools like Funnel Analysis, Segmentation, or Journeys charts to find session replays. You can find session replays with the User Sessions chart or through User Lookup.

If you use a method other than the Android SDK to instrument your events, consider using the [Session Replay Standalone SDK for Android](https://amplitude.com/docs/session-replay/session-replay-android-standalone/).

### Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This happens when a user closes the `[Amplitude] End Session` occurs, but before the Android SDK and Session Replay plugin can process it. When the user uses the app again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

### Session replays don't appear in Amplitude

Session replays may not appear in Amplitude due to:

- Lack of connectivity
- Failed to flush recording before exiting the app
- No events triggered through the Android SDK in the current session
- Sampling

#### Lack of connectivity

Ensure your app has access to the internet then try again.

#### No events triggered through the Android SDK in the current session

Session Replay requires that at least one event in the user's session has the `[Amplitude] Session Replay ID` property. If you instrument your events with a method other than the [Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), the Android SDK may send only the default Session Start and Session End events, which don't include this property.

For local testing, you can force a Session Start event to ensure that Session Replay functions.

1. In Amplitude, in the User Lookup Event Stream, you should see a Session Start event that includes the `[Amplitude] Session Replay ID` property. After processing, the Play Session button should appear for that session.

#### Sampling

As mentioned above, the default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information see, [Sampling rate](#sampling-rate).

#### Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the `[Amplitude] Session Replay ID` property, only that one event in the session has it. Reasons why `[Amplitude] Session Replay ID`  may not be present in an event include:

- The user may have opted out or may not be part of the sample set given the current `sampleRate`. Increasing the `sampleRate` captures more sessions.
- Amplitude events may still send through your provider, but `getSessionReplayProperties()` doesn't return the `[Amplitude] Session Replay ID` property. This can result from `optOut` and `sampleRate` configuration settings. Check that `optOut` and `sampleRate` are set to include the session.

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may be the result of one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a users bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If Session Replay isn't implemented on all pages a user visits, their session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

### Report an Issue

If you encounter any issues with Session Replay that aren't covered in the troubleshooting guide above, please report them on our [GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

When creating an issue, please include:

- A clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- SDK version you're using
- Any relevant error messages or logs

================================================================================
# Session Replay Android Middleware
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-android-middleware
Updated: 2024-10-29
================================================================================

# Session Replay Android Middleware

> **Alpha:** Early access SDK
>
> As an Alpha release, this SDK may contain bugs and cause crashes. Before you enable in production, thoroughly test your app in a controlled environment. For more information about best practices for developer preview SDKs, see [SDK Maintenance and Support](https://amplitude.com/docs/sdks/sdk-maintenance-and-support#sdk-major-version-life-cycle).

This article covers how to install Session Replay using the [Android SDK middleware](https://amplitude.com/docs/sdks/sdk-middleware). If your app already uses the [(maintenance) Amplitude SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk), use this option.

If your app already uses the [(latest) Amplitude Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), use the [Session Replay Android SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin).

If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the Android apps in which it's installed by:
>
> - Asynchronously capturing and processing replay data, to avoid blocking the main user interface thread. The main thread must analyze the view hierarchy, but snapshot capture scheduling and extra processing offloads to the background.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

## Before you begin

The Session Replay Middleware requires that:

1. Your application targets Android.
2. You use version `2.40.1` or higher of the [(maintenance) Amplitude Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk).
3. You can provide a device ID to the SDK.

### Supported Android versions

Session replay supports down to Android 5.0 with a minimum SDK of 21 `minSdk = 21`. This should support over 99.6% of global Android devices according to Google's distribution data in Android Studio.

## Quickstart

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/middleware-session-replay-android/versions) of the Session Replay middleware to your project dependencies.

```kotlin
// Install latest version from Maven Central
implementation("com.amplitude:middleware-session-replay-android:0.26.1")
// You will also need the (maintenance) Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:android-sdk:[2.40.1,3.0.0)")
```

Configure your application code.

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Initialize (maintenance) Amplitude Analytics SDK instance
val amplitude = Amplitude.getInstance()
    .initialize(this, AMPLITUDE_API_KEY)
    // Replay events will be flushed on close as well
    // If setFlushEventsOnClose(false) you must call flush() manually
    .setFlushEventsOnClose(true)

// Create Session Replay Middleware
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0)

// Add session replay middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Track events
amplitude.logEvent("Setup (maintenance) Amplitude Android SDK with session replay!")

// Send replay events to the server
amplitude.uploadEvents()

// You can also call flush() on the middleware directly to only send replay events
// sessionReplayMiddleware.flush()

// Always flush before app exit (onPause)
// override fun Activity.onPause() { sessionReplayMiddleware.flush() }
```

## Configuration

Pass the following options when you initialize the Session Replay middleware:

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `amplitude` | `AmplitudeClient` | Yes | n/a | The maintenance Amplitude SDK client instance to attach to. |
| `sampleRate` | `Number` | No | `0.0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, which selects 40% of sessions over a large number of sessions. |
| `enableRemoteConfig` | `Boolean` | No | `true` | Enables or disables remote configuration for this instance of Session Replay. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig()` | Privacy settings that control which views are masked. Set the mask level with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. See [Mask level](#mask-level). |
| `autoStart` | `Boolean` | No | `true` | Starts screen capture automatically when the middleware initializes. |
| `bandwidthLimitBytes` | `Int?` | No | `null` | _Advanced._ Daily upload limit, in bytes, on metered (for example, cellular) connections. |
| `storageLimitMB` | `Int?` | No | `null` | _Advanced._ Local storage limit, in MB. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Maximum length of a log message. |

### Mask on-screen data

The Session Replay SDK offers four ways to mask user input, text, and other view components.

#### Mask level

Session Replay for Android supports three levels of masking, set through the `privacyConfig` option with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. The default level is `medium`.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks password, email, and phone number input fields. In SDK `0.26.2` and later, `light` also masks any field with sensitive autofill hints (credit card number, expiration, and security code; name; username; postal address and code); autofill-hint detection requires Android 8.0 (API 26) or higher. Earlier versions, including the `middleware-session-replay-android` artifact, mask only the input-field types above. |
| `medium` (default) | Everything in `light`, plus all editable text fields (`EditText`). |
| `conservative` | Everything in `medium`, plus all text views (`TextView`). |

#### Privacy tags in layout XML

Use this option in your application's layout XML.

| View | Description |
| --- | --- |
| `<EditText>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the tag `amp-unmask`. For example: `<EditText android:tag="amp-unmask" android:text="Unmask this">`. |
| `<TextView>` | To mask text within non-input elements, add the tag `amp-mask`. For example, `<TextView android:tag="amp-mask" android:text="Mask this"/>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the tag `amp-block`. For example, `<ImageView android:tag="amp-block"/>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |
| `<WebView>` | To unmask a web view, add the `amp-unmask` tag. For example, `<WebView android:tag="amp-unmask"/>`. |

#### Privacy methods on the Session Replay SDK

Import the `SessionReplay` class, then call one of the methods below from your application's code.

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
```

| Method | Description |
| --- | --- |
| `unmask(view: View)` | To unmask a view manually, call `SessionReplay.unmask(view)` where `view` is a reference to any view that is masked. |
| `mask(view: View)` | To mask text within non-input views, call `SessionReplay.mask(view)` where `view` is a reference to the any view you want to mask. When masked, Session Replay captures masked text as a series of asterisks. |
| `block(view: View)` | To block a non-text view, call `SessionReplay.block(view)` where `view` is a reference to the View you want to block. Session Replay replaces blocked views with a placeholder of the same dimensions. |

#### Privacy modifiers in Jetpack Compose

For composables, use the privacy modifiers instead of layout XML tags or the `SessionReplay` methods. These modifiers require version `0.21.0` or higher of the Session Replay Android SDK or plugin.

Import the modifier you need from `com.amplitude.android.sessionreplay.compose`, then add it to the composable's modifier chain.

```kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
```

| Modifier | Description |
| --- | --- |
| `Modifier.ampMask()` | Masks text that Session Replay captures by default, such as the contents of a `Text` composable. Session Replay captures masked text as a series of asterisks. |
| `Modifier.ampUnmask()` | Unmasks a composable that Session Replay masks by default, such as a `TextField`. |
| `Modifier.ampBlock()` | Blocks a composable. Session Replay replaces blocked composables with a placeholder of the same dimensions and doesn't capture their contents. |

```kotlin
// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)

// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)

// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}
```

A privacy modifier applies to the composable you add it to and to everything nested inside it. When a nested composable has its own privacy modifier, that modifier takes precedence for that composable and its descendants.

### User opt-out

The Session Replay middleware follows the Android SDK's `optOut` setting and doesn't support user opt-outs on its own.

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Set optOut on the Amplitude SDK
val amplitude = Amplitude.getInstance()
        .initialize(this, AMPLITUDE_API_KEY)
        .setOptOut(true)

amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, /* session replay options */))
```

### 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:

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Set serverZone on the Amplitude SDK
val amplitude = Amplitude.getInstance()
        .initialize(this, AMPLITUDE_API_KEY)
        .setServerZone(AmplitudeServerZone.EU)

amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, /* session replay options */))
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```kotlin
// This configuration samples 1% of all sessions
amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, sampleRate = 0.01))
```

### Disable replay collection

After it starts, Session Replay runs in your app until either:

- The user leaves your app.
- You call `sessionReplayMiddleware.stop()`.

Call `sessionReplayMiddleware.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> Keep a reference to the `SessionReplayMiddleware` instance: `val sessionReplayMiddleware = SessionReplayMiddleware(/* session replay options */)`.

Call `sessionReplayMiddleware.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the middleware with `autoStart = false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```kotlin
// Add the middleware without starting capture
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0, autoStart = false)
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Start capture when the user enters a screen you want to record
sessionReplayMiddleware.start()

// Stop capture when the user leaves that screen
sessionReplayMiddleware.stop()
```

You can also use a feature flag product like Amplitude Experiment to enable or disable replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, and add it to your initialization logic:

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Your existing initialization logic with Android SDK
val amplitude = Amplitude.getInstance().initialize(this, AMPLITUDE_API_KEY)

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Middleware
  val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 0.5)
  amplitude.addEventMiddleware(sessionReplayMiddleware)
}
```

### WebView and MapView support (Beta)

By default, Session Replay blocks web views and map views in a capture. To enable capture of these components, use the settings described in [Mask on-screen data](#mask-on-screen-data).

Web view session replay injects JavaScript into the rendered page. To enable this, the SDK sets `javaScriptEnabled` to `true` on the unmasked web view.

### Log Recording

> **Note:** Availability
>
> Log recording is available in Session Replay Android `0.22.0` and later.

Session Replay supports recording logs in Android applications. To enable log recording, send log messages through the `recordLog(level, message, timestamp)` API and configure the limits through `recordLogOptions` parameter while initializing Session Replay.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions

val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)

sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")

// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")
```

Session Replay supports predefined log levels (`Error`, `Warn`, `Log`) and custom log levels. Create custom log levels by passing any string value to `RecordLogLevel(...)`.

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### Timber

If you use `Timber`, you can integrate it with a custom tree.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber

class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}

val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)

Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))
```

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Session Replay storage

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

- Memory usage grows until you call `flush()` to transfer the session replay data to the server.
- Session data isn't retried on failure to transfer to the Amplitude servers.

Amplitude recommends setting `amplitude.setFlushEventsOnClose(true)` in the Amplitude SDK configuration (the default) to send session data to the server on each app exit.

## Jetpack Compose Support (Alpha)

Session Replay supports Jetpack Compose for Android applications. This feature is currently in Alpha. To use Jetpack Compose with Session Replay, ensure you use version `0.20.4` or higher of the Session Replay Android SDK or plugin.

To control what Session Replay captures in a composable, use the [privacy modifiers in Jetpack Compose](#privacy-modifiers-in-jetpack-compose). Masking support for Compose requires `0.21.0` or higher.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay can't capture the following Android views:

  - Canvas Views

================================================================================
# Session Replay React Native SDK Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin
Updated: 2025-03-18
================================================================================

# Session Replay React Native SDK Plugin

- **Package:** `@amplitude/plugin-session-replay-react-native` ([npm](https://www.npmjs.com/package/@amplitude/plugin-session-replay-react-native))
- **Latest version:** 0.5.1

This article covers how to install Session Replay using the [React Native SDK](https://amplitude.com/docs/sdks/analytics/react-native/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](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk).

## Quickstart

#### npm

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

#### yarn

```bash
yarn add @amplitude/plugin-session-replay-react-native
```

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;
```

> **Info:** Using Experiment and Session Replay together
>
> Register Session Replay after Analytics initialization. If your app also uses `@amplitude/plugin-experiment-react-native`, you can register the Experiment plugin before or after Analytics initialization.

## 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](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings) of settings including Sample Rate. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](https://amplitude.com/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";

// ...

<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`.

```js
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.

| Behavior | Android | iOS |
| --- | --- | --- |
| Marker resolution | The nearest explicit mask marker wins. | A masked parent wins over any marker nested inside it. |
| `amp-unmask` nested inside a masked region | The nested subtree becomes visible again in the replay. | The nested subtree stays masked. iOS doesn't support nested unmasking. |
| Where `amp-unmask` takes effect | Anywhere, including inside a region that `amp-mask` covers. | Only outside masked regions, such as on content that the mask level masks. |
| Masked text in the replay | Asterisks that preserve the length of the original text. | No image and no text. The region renders as a flat gray fill. |
| `amp-block` in the replay | Session Replay sends no bitmap for the view, and the player renders a placeholder. | The region renders as a flat gray fill, the same as `amp-mask`. |

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](https://amplitude.com/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](https://amplitude.com/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](https://amplitude.com/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](https://amplitude.com/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.

```js
<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.

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### 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](https://support.amplitude.com).

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](https://amplitude.com/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](https://amplitude.com/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](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

================================================================================
# Session Replay React Native Segment Integration
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-segment-integration
Updated: 2024-07-05
================================================================================

# Session Replay React Native Segment Integration

This article covers how to install Session Replay using the Session Replay React Native Segment plugin. If your React Native app already uses Segment's Analytics React Native library and Amplitude (Actions) destination, use this option.

If you instrument your app with an [Amplitude React Native SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk), use the [Session Replay React Native SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin).

If you use Segment with other options, use the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk).

> **Tip:** Report issues
>
> To report issues with Session Replay for React Native, go to the [Amplitude-TypeScript GitHub repository](https://github.com/amplitude/Amplitude-TypeScript).

> **Warning:** Amplitude Session Plugin required
>
> This plugin requires the `@segment/analytics-react-native-plugin-amplitude-session` plugin to extract session IDs from Amplitude integration data. Add this plugin to your Segment client before you add the session replay plugin.

> **Note:** API key matching
>
> The Amplitude API key in the session replay plugin configuration must match the API key in your Segment Amplitude (Actions) destination.

## Before you begin

Use the latest version of the Session Replay React Native Segment Plugin above `0.0.1-beta.2`.

The Session Replay React Native Segment Plugin requires that:

1. You build your application with React Native.
2. You use Segment's Analytics React Native library for ingestion.
3. You use Segment's Amplitude (Actions) destination.
4. You use Segment's [Amplitude Session Plugin](https://segment.com/docs/connections/sources/catalog/libraries/mobile/react-native/destination-plugins/amplitude-react-native/) to extract session IDs.

## Quickstart

Install the plugin and its dependencies:

#### npm

```bash
npm install @amplitude/segment-session-replay-plugin-react-native
npm install @amplitude/session-replay-react-native @segment/analytics-react-native
```

#### yarn

```bash
yarn add @amplitude/segment-session-replay-plugin-react-native
yarn add @amplitude/session-replay-react-native @segment/analytics-react-native
```

Configure your application code:

```js
import { createSegmentSessionReplayPlugin } from '@amplitude/segment-session-replay-plugin-react-native';
import { createClient } from '@segment/analytics-react-native';
import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude-session';

// Initialize Segment client
const segmentClient = createClient({
  writeKey: 'YOUR_SEGMENT_WRITE_KEY',
});

// Configure session replay plugin
const sessionReplayConfig = {
  apiKey: 'YOUR_AMPLITUDE_API_KEY',
  deviceId: 'YOUR_DEVICE_ID'
};

// Add the Amplitude session plugin first (required for session ID extraction)
await segmentClient.add({ plugin: new AmplitudeSessionPlugin() });

// Add the session replay plugin to Segment
await segmentClient.add({ plugin: createSegmentSessionReplayPlugin(sessionReplayConfig) });
```

## Configuration

The plugin accepts a `SessionReplayConfig` object with the following options:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `string` | Yes | - | Your Amplitude API key. This must match the API key for your Segment Amplitude destination. |
| `deviceId` | `string` | No | - | The device ID for session replay. If not provided, the plugin extracts it from the Segment event context. |
| `sampleRate` | `number` | No | `0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, to represent the fraction of sessions Amplitude randomly selects for replay collection. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](https://amplitude.com/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 after initialization. If set to `false`, manually call the `start()` method to begin capture. |

## How it works

The Segment Session Replay Plugin automatically:

1. Initializes Session Replay: sets up Amplitude Session Replay with your configuration when you add the plugin to Segment.
2. Syncs session data: updates the session ID and device ID for each Segment event by extracting them from event properties or Amplitude integration data.
3. Enriches events: adds session replay properties to `track` and `screen` events before sending them to Segment.
4. Manages lifecycle: handles start and stop operations for session replay based on the plugin lifecycle.

### Event processing

The plugin processes the following Segment event types:

- `TrackEvent`: adds session replay properties to track events.
- `ScreenEvent`: adds session replay properties to screen events.

For these events, the plugin:

- Extracts the session ID from event properties or Amplitude integration data.
- Extracts the device ID from the event context or anonymous ID.
- Adds session replay properties to the event before sending it to Segment.

### Session ID extraction

The plugin extracts session IDs in the following order of priority:

1. From Amplitude integration data: `event.integrations['Actions Amplitude'].session_id`.
2. From event properties: `event.properties.session_id`.
3. Defaults to `-1` if Amplitude finds no session ID.

### Device ID extraction

The plugin extracts device IDs in the following order of priority:

1. From event context: `event.context.device.id`.
2. From anonymous ID: `event.anonymousId`.
3. Defaults to `null` if Amplitude finds no device ID.

## Advanced topics

This section provides examples for more advanced use cases.

### Manual control

Manually control the session replay plugin after initialization:

```js
import { createSegmentSessionReplayPlugin } from '@amplitude/segment-session-replay-plugin-react-native';

// Create the plugin
const sessionReplayPlugin = createSegmentSessionReplayPlugin(sessionReplayConfig);

// Add to Segment
await segmentClient.add(sessionReplayPlugin);

// Later, manually control recording
await sessionReplayPlugin.start();
await sessionReplayPlugin.stop();
```

### Custom configuration

For more advanced configurations, pass additional session replay options:

```js
const sessionReplayConfig = {
  apiKey: 'YOUR_AMPLITUDE_API_KEY',
  sampleRate: 0.1, // Sample 10% of sessions
  enableRemoteConfig: true,
  logLevel: 4, // Debug level
  autoStart: false, // Don't start automatically
};

const sessionReplayPlugin = createSegmentSessionReplayPlugin(sessionReplayConfig);
```

## Troubleshooting

### Session replay properties not added

If the plugin doesn't add session replay properties to your events:

1. Verify that the Amplitude Session Plugin appears before the Session Replay Plugin.
2. Check that your Segment events are of type `track` or `screen`.
3. Confirm that the session replay plugin initializes.

### Session ID not found

If the plugin can't extract session IDs:

1. Verify that you configured the Amplitude Session Plugin correctly.
2. Check that you configured the Segment Amplitude destination correctly.
3. Confirm that events include the required Amplitude integration data.

### Device ID issues

If device ID extraction fails:

1. Check that your Segment events include device information in the context.
2. Verify that the anonymous ID is set in Segment.
3. Consider manually setting the device ID in the plugin configuration.

For additional troubleshooting, go to the [Session Replay React Native SDK Plugin troubleshooting guide](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin).

================================================================================
# Session Replay React Native Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk
Updated: 2024-07-01
================================================================================

# Session Replay React Native Standalone SDK

- **Package:** `@amplitude/session-replay-react-native` ([npm](https://www.npmjs.com/package/@amplitude/session-replay-react-native))
- **Latest version:** 1.0.1

The Session Replay React Native standalone SDK records mobile sessions and uploads them to Amplitude without the Amplitude Analytics SDK. Use it when another analytics provider already instruments your app, or when you manage Amplitude `deviceId` and `sessionId` yourself. If your app already uses the Amplitude React Native Analytics SDK, install the [Session Replay React Native SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin) instead.

You need an Amplitude API key. After you install the package, rebuild the native app. Expo Go doesn't include this native module, so use a development build or a prebuild client.

For changelog details, go to the [package change log](https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/session-replay-react-native/CHANGELOG.md) on GitHub.

## Install the SDK

#### npm

```bash
npm install @amplitude/session-replay-react-native --save
```

#### yarn

```bash
yarn add @amplitude/session-replay-react-native
```

## Quickstart

`init()` configures the SDK and doesn't start capture. Call `start()` after you pass matching `deviceId` and `sessionId` values.

```js
import { init, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
  privacyConfig: {
    maskLevel: "medium",
  },
});

await start();
```

## Correlate replays with analytics events

Session Replay matches a replay to analytics events when the standalone SDK and your analytics SDK send the same `deviceId` and `sessionId`. Pass those values into `init()`, then call `setDeviceId()` and `setSessionId()` whenever either identifier changes.

```js
import {
  setDeviceId,
  setSessionId,
} from "@amplitude/session-replay-react-native";

await setDeviceId("new-device-id");
await setSessionId(Date.now());
```

The standalone SDK doesn't manage sessions for you. Your app or third-party analytics integration must keep both identifiers in sync.

## Configuration

Pass this configuration to `init()`.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `string` | Yes | - | Your Amplitude API key. |
| `deviceId` | `string | null` | No | `null` | Device identifier that matches the device ID on your analytics events. |
| `sessionId` | `number` | No | `-1` | Session identifier that matches the session ID on your analytics events. Use milliseconds since epoch. |
| `sampleRate` | `number` | No | `0` | Fraction of sessions to capture, as a decimal between `0` and `1`. For example, `0.4` selects 40% of sessions over a large sample. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings). |
| `logLevel` | `LogLevel` | No | `LogLevel.Warn` | Sets the log level for the Session Replay SDK. Import `LogLevel` from `@amplitude/session-replay-react-native`, then pass `LogLevel.None`, `LogLevel.Error`, `LogLevel.Warn`, `LogLevel.Verbose`, or `LogLevel.Debug`. |
| `privacyConfig` | `{ maskLevel?: 'light' | 'medium' | 'conservative' }` | No | `{ maskLevel: 'medium' }` | Privacy options. Set `maskLevel` to `'light'`, `'medium'`, or `'conservative'`. |
| `optOut` | `boolean` | No | `false` | Set to `true` to skip session replay collection at initialization. |
| `serverZone` | `'US' | 'EU'` | No | `'US'` | Amplitude server zone. Set to `'EU'` for EU data residency. |

## Methods

### init

Configures the Session Replay SDK. Call this before any other Session Replay method. `init()` doesn't start capture.

```js
import { init } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});
```

### start

Starts recording session replay. Call this after `init()`, and after a previous `stop()` when you want capture to resume.

```js
import { start } from "@amplitude/session-replay-react-native";

await start();
```

### stop

Stops recording session replay.

```js
import { stop } from "@amplitude/session-replay-react-native";

await stop();
```

### setSessionId

Updates the session identifier. Call this whenever the session ID on your analytics events changes.

```js
import { setSessionId } from "@amplitude/session-replay-react-native";

await setSessionId(Date.now());
```

### setDeviceId

Updates the device identifier. Call this whenever the device ID on your analytics events changes. Pass `null` to clear the device ID.

```js
import { setDeviceId } from "@amplitude/session-replay-react-native";

await setDeviceId("new-device-id");
await setDeviceId(null);
```

### getSessionId

Returns the current session identifier from the Session Replay SDK, or `null` if you haven't initialized the SDK.

```js
import { getSessionId } from "@amplitude/session-replay-react-native";

const sessionId = await getSessionId();
```

### setOptOut

Updates opt-out at runtime. Pass `true` to disable replay collection. Pass `false` to allow collection again, subject to sampling and whether you already called `start()`.

```js
import { setOptOut } from "@amplitude/session-replay-react-native";

await setOptOut(true);
await setOptOut(false);
```

### flush

Uploads pending session replay data immediately.

```js
import { flush } from "@amplitude/session-replay-react-native";

await flush();
```

### teardown

Shuts down native Session Replay and clears JavaScript lifecycle state. Call `init()` again before any other Session Replay method.

```js
import { init, start, teardown } from "@amplitude/session-replay-react-native";

await teardown();

await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});
await start();
```

## Mask onscreen data

Session Replay masks or obfuscates views that contain sensitive data or PII. Wrap the region with `AmpMaskView` and set `mask` to `amp-mask`, `amp-unmask`, or `amp-block`. `AmpMaskView` lays out like a normal `View`, so apply the same layout styles you use on a `View`.

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

<AmpMaskView mask="amp-mask">
  <Text>{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.

### Unmask views

To unmask a view that the global mask level otherwise masks, set `mask` to `amp-unmask`.

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

<AmpMaskView mask="amp-unmask">
  <Text>{title}</Text>
</AmpMaskView>;
```

### Block views

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

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

<AmpMaskView mask="amp-block">
  <Text>Session Replay doesn't capture this content</Text>
</AmpMaskView>;
```

### 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.

| Behavior | Android | iOS |
| --- | --- | --- |
| Marker resolution | The nearest explicit mask marker wins. | A masked parent wins over any marker nested inside it. |
| `amp-unmask` nested inside a masked region | The nested subtree becomes visible again in the replay. | The nested subtree stays masked. iOS doesn't support nested unmasking. |
| Where `amp-unmask` takes effect | Anywhere, including inside a region that `amp-mask` covers. | Only outside masked regions, such as on content that the mask level masks. |
| Masked text in the replay | Asterisks that preserve the length of the original text. | No image and no text. The region renders as a flat gray fill. |
| `amp-block` in the replay | Session Replay sends no bitmap for the view, and the player renders a placeholder. | The region renders as a flat gray fill, the same as `amp-mask`. |

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.

### Choose a masking level

Set `privacyConfig.maskLevel` in `init()`.

| Mask level | Description |
| --- | --- |
| `light` | Masks sensitive native text inputs, such as passwords. |
| `medium` (default) | Masks all React Native `TextInput` fields. |
| `conservative` | Masks all `TextInput` fields and standard React Native `Text` content. |

> **Note:** React Native masking limitations
>
> Session Replay doesn't automatically mask text that React Native renders outside standard native text views, including `react-native-svg`, Shopify Skia, and canvas-based renderers. Wrap those regions in `AmpMaskView`.
>
> On Android, `light` doesn't reliably identify credit-card fields. Use `medium` or `conservative`, or wrap the field in `AmpMaskView`, for cross-platform coverage.

Remote configuration on the Session Replay settings page takes precedence over the SDK. This SDK forwards `enableRemoteConfig` to the native iOS and Android Session Replay libraries. Amplitude's Session Replay privacy settings state that if you enable remote configuration and it fails to load, Session Replay doesn't capture sessions.

## Track web views (beta)

By default, Session Replay blocks web views and doesn't track them. To track a web view, wrap it in `AmpMaskView` and set `mask` to `amp-unmask`.

```js
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 supports Amplitude projects that use the EU data center. Set `serverZone` to `'EU'` during initialization.

```js
import { init, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  serverZone: "EU",
});
await start();
```

## Sampling rate

By default, Session Replay captures 0% of sessions. Set `sampleRate` to the percentage of sessions you want to record.

```js
import { init, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
});
await start();
```

When you set `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.

Keep these quota details in mind:

- 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.
- Start with a low rate, for example `.01`. If this value doesn't capture enough replays, raise the rate over a few days. To monitor captured replay volume, go to [View the number of captured sessions](https://amplitude.com/docs/session-replay).

Session Replay supports remote sampling rate settings. Your organization can 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, go to [Account Settings](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings).

## User opt-out

To skip collection at initialization, set `optOut` to `true`. To change this later, call `setOptOut()`. Don't re-run `init()` only to change opt-out.

```js
import { init, setOptOut, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  optOut: true,
});

await setOptOut(false);
await start();
```

## Troubleshooting

### No replay appears

- Call `start()` after `init()`. `init()` configures the SDK and doesn't begin capture.
- Use a non-zero `sampleRate`, or confirm the remote sampling rate on the Session Replay settings page.
- Pass the same `deviceId` and `sessionId` that your analytics events use, and update both when they change.
- Rebuild the native app after you install the package. On iOS, run `pod install` before the rebuild.
- Don't run this SDK in Expo Go. Create a development build or prebuild client instead.

================================================================================
# Session Replay Flutter Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-flutter-standalone-sdk
================================================================================

# Session Replay Flutter Standalone SDK

- **Package:** `amplitude_session_replay` ([pubdev](https://pub.dev/packages/amplitude_session_replay))
- **Latest version:** 0.1.0-beta.5

This article covers the installation of Session Replay for Flutter.

> **Warning:** iOS and Android only
>
> The Session Replay Flutter SDK supports iOS and Android only. The SDK doesn't support Flutter Web, macOS, Windows, or Linux.

> **Warning:** Early Access
>
> Session Replay for Flutter is in Early Access. APIs may change and you should expect significant changes before the feature reaches General Availability.
>
> If you're upgrading from an earlier beta, refer to [Upgrade from earlier beta versions](#upgrade-from-earlier-beta-versions) for breaking API changes.
>
> To report issues with Session Replay for Flutter, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Before you begin

Use the latest version of the [`amplitude_session_replay`](https://pub.dev/packages/amplitude_session_replay) package.

The Session Replay Flutter SDK requires that:

1. Your application runs on iOS 13.0+ or Android 5.0+ (minSdk 21).
2. Your project uses Dart SDK 3.7.2 or later and Flutter SDK 3.29.2 or later.
3. You can provide a `device ID` and `session ID` to the SDK. These values must match the identifiers you send as event properties to Amplitude.

The SDK doesn't provide session management. Your application or a third-party integration must update the SDK when the session ID or device ID changes.

### Compatibility

| Requirement | Minimum version |
| --- | --- |
| Dart SDK | 3.7.2 |
| Flutter SDK | 3.29.2 |
| iOS | 13.0 |
| Android minSdk | 21 (Android 5.0) |
| Android compileSdk | 36 |

## Quickstart

Add Session Replay to your `pubspec.yaml`:

```yaml
dependencies:
  amplitude_session_replay: ^0.1.0-beta.5
```

Then run `flutter pub get`.

`SessionReplay` is a process-wide singleton. Access it through `SessionReplay.instance`, and don't construct it directly.

Configure your application code:

1. Call `SessionReplay.instance.init()` with a `SessionReplayConfig`, passing your API key, device ID, and session ID. `init()` is synchronous. It stores the config and installs the message channel handler.
2. Call `start()` to initialize the native SDK and begin recording.
3. When the session ID or device ID changes, call `setSessionId()` or `setDeviceId()` to keep Session Replay synchronized.

```dart
import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // init() is synchronous: it stores the config and installs the channel handler.
  SessionReplay.instance.init(
    SessionReplayConfig(
      apiKey: 'YOUR_AMPLITUDE_API_KEY',
      deviceId: 'your-device-id',
      sessionId: DateTime.now().millisecondsSinceEpoch,
      sampleRate: 0.1,
    ),
  );

  // start() initializes the native SDK and begins recording.
  await SessionReplay.instance.start();

  runApp(const MyApp());
}
```

## Configuration

Pass the following options through `SessionReplayConfig` when you call `SessionReplay.instance.init()`:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `String` | Yes | — | Your Amplitude API key for authentication and data routing. |
| `deviceId` | `String` | Yes | — | Device identifier. Must match the device ID you send with Amplitude events. Must be at least 6 characters. |
| `sessionId` | `int` | No | `-1` | Session identifier in milliseconds since epoch. A value of `-1` means no active session, and Session Replay doesn't record. Must match the session ID you send with Amplitude events. |
| `sampleRate` | `double` | No | `0.0` | Fraction of sessions to capture for replay (0.0–1.0). For example, `0.4` captures 40% of sessions. |
| `logLevel` | `LogLevel` | No | `LogLevel.warn` | Logging verbosity. Options: `LogLevel.off`, `LogLevel.error`, `LogLevel.warn`, `LogLevel.log`, `LogLevel.debug`. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig.medium` | Automatic masking behavior. Options: `PrivacyConfig.conservative`, `PrivacyConfig.medium`, `PrivacyConfig.light`. |
| `enableRemoteConfig` | `bool` | No | `true` | Enables [remote configuration](#remote-configuration) from Amplitude servers. |
| `optOut` | `bool` | No | `false` | When `true`, Session Replay doesn't record or upload data. Use `setOptOut()` to change at runtime. |
| `serverZone` | `ServerZone` | No | `ServerZone.us` | Server zone for data residency. Set to `ServerZone.eu` for EU data center. |

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Mask onscreen data

Session Replay provides three Flutter widgets for privacy control. These widgets apply to the entire subtree of the wrapped widget. Priority order: `AmpBlock` > `AmpMask` > `AmpUnmask`.

#### Privacy levels

The `privacyConfig` option controls automatic masking behavior:

| Level | Behavior |
| --- | --- |
| `PrivacyConfig.conservative` | Masks all text and all form fields. |
| `PrivacyConfig.medium` (default) | Masks all form fields and text inputs. |
| `PrivacyConfig.light` | Masks only password fields. |

#### AmpMask

Replaces every character of captured text with an asterisk (`*`), preserving the original text length and layout. Use this to protect sensitive information that the automatic privacy level doesn't catch:

```dart
AmpMask(
  child: Text('Sensitive information'),
)
```

#### AmpBlock

Blocks an entire subtree from recording and replaces it with a placeholder. Use this for highly sensitive content:

```dart
AmpBlock(
  child: TextField(
    decoration: InputDecoration(labelText: 'Password'),
  ),
)
```

#### AmpUnmask

Prevents automatic masking from privacy level rules. Use this to reveal content that the privacy level would otherwise mask. `AmpUnmask` can't override a manual `AmpMask` or `AmpBlock`:

```dart
AmpUnmask(
  child: Text('Public content'),
)
```

### User opt-out

To opt users out of session replay collection, pass `optOut: true` during initialization, or call `setOptOut(optOut: true)` at runtime. Opted-out users don't record or upload replay data.

```dart
await SessionReplay.instance.setOptOut(optOut: true);
```

### EU data residency

Amplitude customers who use the EU data center can access Session Replay. Set `serverZone` to `ServerZone.eu` during initialization.

```dart
SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch,
    serverZone: ServerZone.eu,
  ),
);
```

### Sampling rate

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

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.

Keep the following in mind 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 over the course of 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 the course of a few days. For ways to monitor the number of session replays captured, see [View the number of captured sessions](https://amplitude.com/docs/session-replay#view-the-number-of-captured-sessions).
- Replays with [processing errors](https://amplitude.com/docs/session-replay/session-replay-plugin#troubleshooting) don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

```dart
SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch,
    sampleRate: 0.01, // Capture 1% of sessions
  ),
);
```

### Update the session ID

When your session ID changes (for example, on user login or session timeout), update Session Replay:

```dart
final newSessionId = DateTime.now().millisecondsSinceEpoch;
await SessionReplay.instance.setSessionId(newSessionId);
```

### Start and stop recording

Control recording for specific pages or features:

```dart
// Stop recording before entering a restricted area
await SessionReplay.instance.stop();

// Resume recording after leaving the restricted area
await SessionReplay.instance.start();
```

### Disable replay collection

After you enable Session Replay, it runs on your app until either:

- The user leaves your app.
- You call `SessionReplay.instance.stop()`.
- You call `SessionReplay.instance.dispose()`.

Call `SessionReplay.instance.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

Call `SessionReplay.instance.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

### Hybrid and add-to-app

If your Flutter module runs inside a native iOS or Android host that already integrates the Amplitude Session Replay native SDK, call `SessionReplay.instance.attach()` instead of `init()`. This installs the message channel handler and lets the host app's native SDK own the API key, device ID, session ID, sampling, masking, and upload lifecycle. Don't pass a `SessionReplayConfig`. The native SDK owns configuration in this mode.

```dart
import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // The native SDK owns config and lifecycle. attach() only installs the
  // channel handler so native start commands reach the Flutter engine.
  SessionReplay.instance.attach();

  runApp(const MyApp());
}
```

In hybrid mode, the native SDK owns the recording lifecycle. `start()`, `stop()`, `flush()`, `setOptOut()`, `setSessionId()`, and `setDeviceId()` log a warning and no-op. Configure those on the native SDK instead. `dispose()` tears down only the Dart channel handler and engine, and leaves the native SDK alone.

If your app runs multiple Flutter engines (for example, `FlutterEngineGroup` with several Dart entry points), call `attach()` in each entry point. Each engine runs its own isolate with its own `SessionReplay.instance`.

## Methods

Call these methods on the `SessionReplay.instance` singleton:

| Method | Returns | Description |
| --- | --- | --- |
| `init(SessionReplayConfig)` | `void` | Register the config and install the channel handler (Flutter-only mode). Synchronous and one-shot per lifecycle. Call `dispose()` before re-initializing with a new config. |
| `attach()` | `void` | Install the channel handler in hybrid mode, where the native SDK owns configuration and lifecycle. Use instead of `init()`. |
| `start()` | `Future<void>` | Start recording. Initializes the native SDK on first call. |
| `stop()` | `Future<void>` | Stop recording. Call `start()` to resume. |
| `dispose()` | `Future<void>` | Release all resources and return the singleton to its uninitialized state. Call `init()` or `attach()` again to reuse it. |
| `flush()` | `Future<void>` | Force-upload any pending replay data. Useful before the app backgrounds or terminates. |
| `setSessionId(int)` | `Future<void>` | Update the session ID. |
| `sessionId()` | `Future<int>` | Get the current session ID. |
| `setDeviceId(String)` | `Future<void>` | Update the device ID. |
| `deviceId()` | `Future<String>` | Get the current device ID. |
| `setOptOut(optOut: bool)` | `Future<void>` | Toggle opt-out at runtime. When `true`, stops recording and data upload. |
| `optOut` (getter) | `bool` | Get the current opt-out status. |

### Lifecycle

![Session Replay SDK lifecycle: init(config) creates the Initialized state, start() moves to Started, stop() moves to Stopped, start() returns Stopped to Initialized, dispose() from any state moves to Disposed, and init(config) revives Disposed back to Initialized.](https://amplitude.com/docs/images/diagrams/flutter-session-replay-lifecycle.svg) ![Session Replay SDK lifecycle: init(config) creates the Initialized state, start() moves to Started, stop() moves to Stopped, start() returns Stopped to Initialized, dispose() from any state moves to Disposed, and init(config) revives Disposed back to Initialized.](https://amplitude.com/docs/images/diagrams/flutter-session-replay-lifecycle.dark.svg)

`init()` is one-shot per lifecycle: it's only callable from the uninitialized (or disposed) state. To re-initialize with a new config, call `dispose()` first, then `init()` again.

You can call `dispose()` from any state. It returns the singleton to its uninitialized state, so a later `init()` or `attach()` cleanly revives it. Use `dispose()` for permanent teardown only. To temporarily pause and resume recording, use `stop()` and `start()` instead.

## Upgrade from earlier beta versions

Version `0.1.0-beta.5` simplifies installation and reworks the `SessionReplay` API. `SessionReplay` is now a process-wide singleton, and the `SessionReplayWidget` wrapper is no longer required.

### Breaking changes

For Flutter-only apps:

| Old API | New API |
| --- | --- |
| `SessionReplay(config)` constructor | `SessionReplay.instance.init(config)` |
| `SessionReplayWidget(sessionReplay: ..., app: ...)` | Removed. No widget wrapping needed |
| `sessionReplayProperties()` | Removed. Replays match by `deviceId` and `sessionId` |

For hybrid and add-to-app:

| Old API | New API |
| --- | --- |
| `SessionReplayConfig.shouldInitializeNativeSDK: false` | Removed. Call `SessionReplay.instance.attach()` |
| `ensureInitialized()` | `SessionReplay.instance.attach()` |

### Flutter-only apps

Replace the constructor and `SessionReplayWidget` wrapper with `SessionReplay.instance.init()` and `start()`:

```dart
// Before
final sessionReplay = SessionReplay(
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
runApp(SessionReplayWidget(sessionReplay: sessionReplay, app: const MyApp()));
await sessionReplay.start();

// After
SessionReplay.instance.init(          // synchronous, no await
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
await SessionReplay.instance.start();
runApp(const MyApp());                // no SessionReplayWidget wrapping needed
```

- `init()` is one-shot per lifecycle. Call `await SessionReplay.instance.dispose()` before re-initializing with a new config.
- Setters (`setSessionId()`, `setDeviceId()`, `setOptOut()`) still work between `init()` and `start()`.

### Hybrid and add-to-app

Replace the placeholder config and widget wrapper with a single `attach()` call:

```dart
// Before — placeholder config + widget wrapper
return SessionReplayWidget(
  sessionReplay: SessionReplay(
    const SessionReplayConfig(
      apiKey: 'YOUR_API_KEY',
      deviceId: 'YOUR_DEVICE_ID',
      shouldInitializeNativeSDK: false,
    ),
  ),
  app: MaterialApp(...),
);

// After — one line per entry point, no config needed
void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SessionReplay.instance.attach(); // native owns config and lifecycle
  runApp(const MyApp());
}
```

- Call `attach()` in every Dart entry point. Each Flutter engine is its own isolate with its own `SessionReplay.instance`.
- Remove any host-app native SDK version pin (for example, a Gradle `resolutionStrategy.force(...)`) and let it resolve within the range the Flutter plugin declares.

### Session Replay properties

Remove all calls to `sessionReplayProperties()`. Amplitude matches replays to analytics events by `deviceId` and `sessionId`. Make sure those match the identifiers you send with your analytics events. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

The `AmpMask`, `AmpUnmask`, and `AmpBlock` privacy widgets are unchanged.

## Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

> **Note:** Consent management and Session Replay
>
> While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

### Retention period

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

If you purchase extra session volume, Amplitude retains raw replay data for 90 days 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.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

### DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a `[Amplitude] Session Replay ID` event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

```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](https://amplitude.com/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 on which you use Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

## Known limitations

1. **Beta status**: APIs may change. Expect breaking changes before the stable release.
2. **RSuperellipse capture**: Requires Flutter 3.32 or later. Base functionality works on Flutter 3.29.2+.
3. **Multi-view apps**: In Flutter-only mode, the SDK captures the app's primary render view. For hybrid and add-to-app setups that run multiple Flutter engines, call `attach()` in each Dart entry point (refer to [Hybrid and add-to-app](#hybrid-and-add-to-app)).
4. **Remote config override**: When `enableRemoteConfig` is `true`, server settings can override the local `sampleRate` and privacy settings.
5. **Native SDK dependencies**: iOS uses `AmplitudeSessionReplay` ~>0.12.2. Android uses `session-replay-android` \[0.27.0, 0.28.0).

## Troubleshooting

### Session replays don't appear in Amplitude

Session replays may not appear because of:

- Lack of network connectivity.
- Sampling excluded the session (`sampleRate` too low).
- No events sent with matching `deviceId` and `sessionId` for the session.
- A missing `SessionReplay.instance.start()` call after `init()`.

#### Verify your configuration

1. Check that `sampleRate` is greater than `0`. The default is `0.0`, which captures no sessions.
2. Confirm you call `SessionReplay.instance.start()` after `SessionReplay.instance.init()`.
3. Ensure the `apiKey`, `deviceId`, and `sessionId` match the values you send with analytics events.

#### Verify network connectivity

Ensure your app has access to the internet and try again.

#### Check sample rate

The default `sampleRate` is `0.0`. Update the rate to a higher number. For more information, refer to [Sampling rate](#sampling-rate).

### Session Replay processing errors

Replays appear in Amplitude within minutes of ingestion. Delays or errors may result from:

- Mismatched API keys or device IDs between Session Replay and your analytics instrumentation.
- Session Replay references the wrong project.
- Short sessions. If a user bounces within a few seconds of initialization, the SDK may not have time to upload replay data.

================================================================================
# Ingestion Monitor
URL: https://amplitude.com/docs/session-replay/ingestion-monitor
================================================================================

# Ingestion Monitor

Amplitude provides the Ingestion Monitor to help debug Session Replay implementation issues by tracking Session Replay status over time.

Access the Ingestion Monitor from:

- The top-right of the Session Replay section of your project's **Users & Sessions** tab.
- Any individual replay that displays an error.

### Tracked statuses

The Ingestion Monitor displays charts with the count of each status over a time range that you select:

- Successful request (status 200)
- Throttling errors (status 429)
- Quota exceeded errors (status 402)
- Invalid session IDs

Use these charts to debug unavailable session replays and monitor the health of your Session Replay implementation.

## Troubleshooting

### Short or incomplete replays

If you see short replays (less than 10 seconds) or replays that appear incomplete, check the Ingestion Monitor for 429 throttling errors.

A 429 error means your application sends too many Session Replay requests. Amplitude throttles these requests. Because replays consist of multiple chunks of data, some chunks may not send successfully, which produces incomplete or unusually short replays.

To resolve 429 throttling errors:

1. Reduce your Session Replay sample rate to lower the request volume per second.
2. Monitor the 429 error count in the Ingestion Monitor to confirm that throttling errors decrease after you adjust the sample rate.

================================================================================
# Session Replay and Heatmap Settings
URL: https://amplitude.com/docs/session-replay/session-replay-settings
================================================================================

# Session Replay and Heatmap Settings

Use Session Replay settings to manage replay capture across your organization's projects. From these settings, you can control sample rates, enable or disable capture, and monitor quota usage.

The organizational settings also let admins and managers view or modify [Session Replay](https://amplitude.com/docs/session-replay) settings for the projects they have access to.

The main settings page displays your organization's total session replay capture plan allowance and current use. The page also lists projects where you can toggle session capture and heatmap capture, and view the sample rate, instrumentation status, masking setting, and masking overrides.

On each project's settings page, find project-level controls for:

- Sampling
- Dynamic Sampling
- Masking Level
- Masking Overrides
- Console Tracking

## Sampling

View and set the sampling rate for any condition you define. The Sampling section shows a monthly estimate of sessions that match the conditions you define, and estimates how many sessions Amplitude captures. By default, Session Replay uses the **Any Session** condition. For more information about conditions, refer to [Targeted Replay Capture](https://amplitude.com/docs/session-replay/targeted-replay-capture).

## Dynamic sampling

If you're unsure how to balance your sample rate against your monthly quota, dynamic sampling may help. Dynamic sampling adjusts the sample rate each day so you use your full quota by month end. Dynamic sampling helps you stay within your quotas, but Amplitude can't guarantee an exact 100% match or prevent overage. Choose which projects use dynamic sampling. Session Replay quota is org-wide, but the sampling rate is per project. If you enable dynamic sampling on multiple projects, those projects share the same sample rate.

Session Replay doesn't support dynamic sampling if you use [targeted session replay capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) in any project or set the sample rate in the SDK for any project.

## Masking level

Set the [masking level](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay#masking-levels) for all captured sessions.

## Masking overrides

Define overrides for the masking level you set. For more information, refer to [Manage privacy settings for Session Replay](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay#override-preset-policy-levels).

## Console tracking

Enable or disable console tracking, and set the types of console information you want to capture. Select one or more from `Info`, `Log`, `Warn`, and `Error`.

> **Tip:**
>
> The Session Replay viewer also includes a **Network** tab in the _DevTools_ section. Use the Network tab alongside console logs to inspect network requests captured during a replay. For details, go to [Session Replay viewer](https://amplitude.com/docs/session-replay/session-replay-viewer).

## Multi-tab behavior

Session Replay captures activity on the currently focused tab. When the user switches between tabs, the replay follows their focus and automatically switches to show the tab they're actively viewing.

When the user switches tabs, the replay cuts directly to the new tab with a fresh snapshot of the new tab's current state. Session Replay doesn't actively capture background tabs while out of focus. The event timeline captures and displays events from all tabs, regardless of which tab had focus at the time.

While viewing a Session Replay, you can't manually switch to view background tabs. The replay strictly follows the user's actual focus. If the user switches away from the browser entirely, the replay shows an inactive period while displaying the last focused tab.

================================================================================
# Session matching
URL: https://amplitude.com/docs/session-replay/session-matching
================================================================================

# Session matching

Session Replay matches replays to Amplitude data to provide a complete view of the user journey. Session matching links device and session information from Session Replay to Amplitude sessions.

Session Replay offers multiple session matching options. Choose the option that works best for your technical constraints and session definitions.

## Session matching options

Amplitude provides options to match sessions directly, match events based on time, or match by Amplitude session ID.

### Match Amplitude sessions (recommended)

Match Amplitude sessions based on your project's session definition. Amplitude session matching respects how you configure sessions in your Amplitude project settings, including sessions you define with event properties, timeout windows, or start/end events.

If you use the default `session_id`, Session Replay works automatically with no additional configuration.

If you use a custom session property, configure the Session Replay SDK to extract and send that same property value. Session Replay then matches sessions using your project's custom session definition, which provides the most accurate alignment between replay data and analytics sessions.

#### Requirements for custom session definitions

**Minimum SDK versions:**

- Browser SDK Plugin: `@amplitude/plugin-session-replay-browser` version 1.10.0 or later.
- Browser Standalone SDK: `@amplitude/session-replay-browser` version 1.17.0 or later.
- iOS (plugin and standalone): Session Replay for iOS version 0.11.2 or later.
- Android (plugin and standalone): Session Replay for Android version 0.26.4 or later.

**Project configuration:**

- Configure your custom session definition in _Settings > Projects > Session Definitions_.
- Use the "Counted based on <> Property" option to define sessions by a specific property.
- For more details, refer to [Track sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions).

**Constraints:**

- The session replay ID has the format `<deviceId>/<sessionId>`. Session Replay uses `/` as a delimiter, so neither `deviceId` nor custom session ID values can contain `/`.
- Accepted characters for both `deviceId` and custom session IDs: `a-z A-Z 0-9 _ - . | @ : =`.
- If you need an additional character, contact support.

#### Configure the SDK for custom session definitions

The following code examples apply only if you configured a custom session definition in your Amplitude project settings.

**Browser SDK Plugin:**

Pass a method that extracts the custom session ID from Amplitude events:

```javascript
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";

const sessionReplayTracking = sessionReplayPlugin({
  customSessionId: (event) => {
    const props = event.event_properties;
    if (!props) {
      return;
    }
    const sessionId = props["your_custom_session_id_property"];
    return sessionId;
  },
});
amplitude.add(sessionReplayTracking);

amplitude.init(AMPLITUDE_API_KEY);
```

**Standalone SDK:**

The standalone SDK treats custom session IDs and timestamp-based session IDs the same way. Pass the session ID to the standalone SDK, and send that same session ID to Amplitude as an event property that matches your project's custom session definition:

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";

// Initialize Session Replay with session ID
sessionReplay.init(AMPLITUDE_API_KEY, {
  customSessionId: (event) => {
    const props = event.event_properties;
    if (!props) {
      return;
    }
    const sessionId = props["your_custom_session_id_property"];
    return sessionId;
  },
});
```

Ensure the session ID property name matches the property you configured in your project's custom session definition (_Settings > Projects > Session Definitions_).

**Mobile SDKs:**

The iOS and Android SDKs accept a string session ID directly instead of a callback. Set the value whenever your custom session changes, and send the same value as the session-defining event property to Amplitude:

- iOS: set the `customSessionId` property on the standalone SDK or the plugin. Refer to [Custom session IDs on iOS](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk#custom-session-ids).
- Android: call `setCustomSessionId` on the standalone SDK or the plugin. Refer to [Custom session IDs on Android](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone#custom-session-ids).

### Time-based event matching

Build sessions using 30- or 60-minute time windows based on event activity. Use time-based event matching if your analytics pipeline doesn't include a session ID on events, such as a homegrown pipeline that sends only event timestamps to S3.

Time-based matching links replays to analytics events by device ID and overlapping time windows. It's slightly less precise than true session matching, but still delivers a reliable and useful journey view.

#### Session Replay SDK still needs a session ID

The standalone Session Replay SDK needs a `sessionId` before replay data can be associated with a session. This ID is separate from how Amplitude matches replays to analytics events.

With time-based event matching, you can generate the Session Replay `sessionId` entirely on the frontend. It doesn't need to match your analytics session ID or any field in your analytics pipeline.

To align with 60-minute time-based matching, round the current time down to the start of the hour and pass that Unix timestamp in milliseconds to the SDK:

```javascript
const HOUR_MS = 60 * 60 * 1000;
const sessionId = Date.now() - (Date.now() % HOUR_MS);

await sessionReplay.init(AMPLITUDE_API_KEY, {
  deviceId: "<string>",
  sessionId,
}).promise;

// Call setSessionId when the hour bucket changes
await sessionReplay.setSessionId(Date.now() - (Date.now() % HOUR_MS)).promise;
```

With time-based event matching, the Session Replay `sessionId` is an upload bucket for replay data. It doesn't need to match analytics, but it should still be a valid Unix timestamp in milliseconds so the server accepts the upload.

For 30-minute matching windows, use `30 * 60 * 1000` instead of `HOUR_MS`. Keep the bucket size aligned with the time window you configure in _Organization Settings > Session Replay_.

For more information about initializing the standalone SDK, go to [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk).

### Session ID matching (legacy)

Match based on the Amplitude `session_id`, even if the `session_id` doesn't align with custom session definitions. Session ID matching exists for backward compatibility and requires no changes.

## Choose a matching option

Match Amplitude sessions whenever possible, including custom session definitions, as long as you send the same session ID to both Amplitude and Session Replay.

If your analytics pipeline doesn't include a session ID on events, use time-based event matching and generate a frontend session ID for the Session Replay SDK as described in [Session Replay SDK still needs a session ID](#session-replay-sdk-still-needs-a-session-id).

## Configure session matching

Configure session matching at the organization level, not at the project level. Configure your session matching option in _Organization Settings > Session Replay_. For more information, refer to [Session Replay and Heatmap Settings](https://amplitude.com/docs/session-replay/session-replay-settings).

> **Note:** Organization-level configuration
>
> Session matching applies to all projects in your organization. Configure this setting in _Organization Settings_, not per project.

To configure session matching in your Session Replay SDK implementation, the exact steps depend on which SDK you use:

- **Browser SDK Plugin**: Refer to [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) for configuration details.
- **Standalone SDK**: Refer to [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk) for configuration details.
- **iOS**: Refer to [Session Replay iOS Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk#custom-session-ids) or [Session Replay iOS Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin#custom-session-ids).
- **Android**: Refer to [Session Replay Android Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone#custom-session-ids) or [Session Replay Android Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin#custom-session-ids).

When using custom session IDs, ensure the Session Replay SDK sends the same session ID value that you use in Amplitude, so that sessions match correctly.

Session matching changes are quick and reversible. You can change your matching option at any time without losing data.

> **Note:** Historical data
>
> Changing your session matching option doesn't affect historical data. The change impacts how Amplitude matches and views replays going forward.

## Frequently asked questions

### Does session matching require re-instrumentation?

Usually no. If you use custom sessions, ensure the Session Replay SDK sends the same session ID value you already use in Amplitude.

### What are the tradeoffs with time-based matching?

Time-based matching has slightly less precision at session boundaries, but still provides a clear and actionable view of the user journey.

### Can I change the matching option later?

Yes. You can change session matching quickly, and you can fully reverse the change.

### Does changing the matching option affect historical data?

You don't lose any data. The change impacts how Amplitude matches and views replays going forward.

### Is Amplitude deprecating session ID matching?

No. Amplitude continues to support session ID matching, though Amplitude recommends newer options for most use cases.