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](/docs/sdks/session-replay/session-replay-android-plugin) instead. {% 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 %} {% partial file="session-replay/sr-android-performance.md" /%} ## Before you begin The Session Replay Standalone SDK requires that: 1. Your application is Android-based. 2. You track sessions with a timestamp that you can pass to the SDK. Inform the SDK whenever a session timestamp 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`. {% partial file="session-replay/sr-android-supported-versions.md" /%} ## 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.26.3") ``` 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`. 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 | | ------------------------------------ | ------------ | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `deviceId` | `String` | Yes | `null` | Identifier for the device running your application. | | `sessionId` | `Long` | Yes | `null` | Identifier for the user's current session. The value must be in milliseconds since epoch (Unix Timestamp). | | `sampleRate` | `Number` | No | `0.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 randomly selected for replay collection. Over many sessions, `0.4` selects `40%` of sessions. | | `optOut` | `Boolean` | No | `false` | Sets permission to collect replays for sessions. A value of `true` prevents Amplitude from collecting session replays. | | `logger` | `Logger` | No | `LogcatLogger` | Sets a custom `logger` class from the Logger to emit log messages to a destination. Set to `null` to disable logging. | | `serverZone` | `ServerZone` | No | `ServerZone.US` | `ServerZone.EU` or `ServerZone.US`. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in the EU data center. | | `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` | Maximum number of logs per session. | | `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | 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 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, optOpt = true, /* other session replay options */ ) ``` {% partial file="session-replay/sr-eu-data-residency.md" /%} ```kotlin // Set serverZone to EU val sessionReplay = SessionReplay( apiKey = API_KEY, serverZone = ServerZone.EU, /* other session replay options */ ) ``` {% partial file="session-replay/sr-sampling-rate.md" /%} ```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.shutdown()`. Call `sessionReplay.shutdown()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area. Create a new instance `sessionReplay = SessionReplay(apiKey = API_KEY, /* options */)` 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 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 */ ) ``` {% 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" /%} {% partial file="session-replay/sr-android-jetpack-compose.md" /%} {% partial file="session-replay/sr-android-known-limitations.md" /%} {% partial file="session-replay/sr-android-troubleshooting.md" /%}