This article covers how to install Session Replay using the Android SDK plugin. If your app is already instrumented with Amplitude, use this option. If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](/docs/sdks/session-replay/session-replay-android-standalone).

{% partial file="session-replay/sr-android-performance.md" /%}

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.

{% callout type="tip" heading="Report issues" %}
To report issues with Session Replay for Android, go to the [AmplitudeSessionReplay-Android GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).
{% /callout %}

## Before you begin

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

{% tabs tabs="Android-Kotlin, Android (maintenance)" %}
{% tab name="Android-Kotlin" %}
If you use the current [Android-Kotlin SDK](/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.

{% /tab %}
{% tab name="Android (maintenance)" %}
If you use the [maintenance Android SDK](/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](/docs/sdks/analytics/android/android-sdk).
3. You can provide a device ID to the SDK.

{% /tab %}
{% /tabs %}

{% partial file="session-replay/sr-android-supported-versions.md" /%}

## Quickstart

{% tabs tabs="Kotlin SDK, Legacy SDK" %}
{% tab name="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.26.3")
// You will also need the Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:analytics-android:[1.16.7, 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)
```

{% /tab %}
{% tab name="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() }
```

{% /tab %}
{% /tabs %}

{% callout type="info" heading="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.
{% /callout %}

## 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 to select for replay collection. Use a decimal between 0 and 1. For example, `0.4` randomly 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.                                                                          |
| `maskLevel`                          | String  | No       | `medium` | Sets the [privacy mask level](#mask-level).                                                                                                                                     |
| `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.                                                                                                                                       |

{% partial file="session-replay/sr-remote-config-test.md" /%}

{% partial file="session-replay/sr-android-mask-data.md" /%}

### 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 */))
```

{% partial file="session-replay/sr-eu-data-residency.md" /%}

```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 */))
```

{% partial file="session-replay/sr-sampling-rate.md" /%}

```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 `amplitude.remove(sessionReplayPlugin)`.

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

{% callout type="note" heading="Keep a reference" %}
This action requires keeping a reference to the SessionReplayPlugin instance `val sessionReplayPlugin = SessionReplayPlugin(/* session replay options */)`.
{% /callout %}

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

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)
}
```

{% partial file="session-replay/sr-android-webview-mapview.md" /%}

{% partial file="session-replay/sr-android-log-recording.md" /%}

{% partial file="session-replay/sr-data-retention.md" /%}

{% partial file="session-replay/sr-android-storage.md" /%}

Amplitude recommends setting `flushEventsOnClose = true` in the Amplitude SDK Configuration (the default) to send session data to the server on each app exit.

{% partial file="session-replay/sr-android-jetpack-compose.md" /%}

{% partial file="session-replay/sr-android-known-limitations.md" /%}

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

{% partial file="session-replay/sr-android-troubleshooting.md" /%}

### 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.
- The `optOut` configuration is enabled 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](/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 Session Replay isn't implemented 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).