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

This article covers how to install Session Replay using the [Android SDK middleware](/docs/sdks/sdk-middleware). If your app already uses the [(maintenance) Amplitude SDK](/docs/sdks/analytics/android/android-sdk), use this option.

If your app already uses the [(latest) Amplitude Android SDK](/docs/sdks/analytics/android/android-kotlin-sdk), use the [Session Replay Android SDK Plugin](/docs/sdks/session-replay/session-replay-android-plugin).

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" /%}

## 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](/docs/sdks/analytics/android/android-sdk).
3. You can provide a device ID to the SDK.

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

## 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                                                                                                                                             |
| ------------------------------------ | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sampleRate`                         | `number` | No       | `0`     | Controls the fraction of sessions selected for replay collection. Use a decimal between 0 and 1. For example, `0.4` randomly selects `40%` of sessions. |
| `recordLogOptions.logCountThreshold` | `Int`    | No       | `1000`  | Maximum number of logs per session.                                                                                                                     |
| `recordLogOptions.maxMessageLength`  | `Int`    | No       | `2000`  | Maximum length of a log message.                                                                                                                        |

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

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

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

```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.add(SessionReplayMiddleware(amplitude, /* session replay options */))
```

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

```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.stopRecording()`.

Call `sessionReplayMiddleware.stopRecording()` 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" %}
Keep a reference to the `SessionReplayMiddleware` instance: `val sessionReplayMiddleware = SessionReplayMiddleware(/* session replay options */)`.
{% /callout %}

Call `sessionReplayMiddleware.startRecording()` 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, 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)
}
```

{% 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 `amplitude.setFlushEventsOnClose(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" /%}