Migrate Session Replay Android to version 1.0
Session Replay Android 1.0 introduces a new Compose capture architecture and a Gradle plugin. Use this guide to upgrade an existing 0.x or 1.0 beta integration. For a new installation, follow the Analytics plugin setup or standalone setup.
Compose capture requires the Gradle plugin
Starting with Session Replay Android 1.0, Compose capture requires the com.amplitude.session-replay Gradle plugin. Install and apply the plugin in your Android app module. Adding the runtime dependency or initializing SessionReplayPlugin alone doesn't enable Compose capture.
Prerequisites
- An existing Session Replay Android integration and access to its Gradle build configuration.
- For the Analytics plugin integration, Amplitude Analytics Android SDK
1.31.0or later. - Your existing sampling, privacy, opt-out, and remote configuration settings to preserve during migration.
For Compose capture, the com.amplitude.session-replay Gradle plugin also requires:
- Jetpack Compose UI
1.9or later (tested through1.13.0-beta01). - Android Gradle Plugin (AGP)
8.5or later. - JDK
17or later to run Gradle.
The Gradle plugin checks Compose internals at build time. An error such as cannot instrument ... Compose version ... not supported means the resolved Compose dependency is incompatible with the plugin. Upgrade Compose or adjust your Compose BOM to a supported version, then rebuild.
1. Update Gradle configuration
Configure Maven Central for plugin resolution, then apply com.amplitude.session-replay version 1.0.0 in your Android app module. Follow the setup for your integration:
| Integration | Gradle changes |
|---|---|
| Analytics plugin | Let the Gradle plugin add the core replay runtime and Analytics replay plugin. Remove old explicit session-replay-android and plugin-session-replay-android dependencies. Keep your analytics-android dependency at 1.31.0 or later. |
| Standalone SDK | Set autoAddDependencies = false and declare com.amplitude:session-replay-android:1.0.0. |
| Maintenance SDK middleware | Set autoAddDependencies = false and declare com.amplitude:middleware-session-replay-android:1.0.0. Keep your maintenance Analytics SDK dependency. |
Keep the Gradle plugin and replay runtime versions aligned. If you manage versions in a version catalog or dependency constraints, update those declarations too. Don't disable the integration check to hide a version mismatch.
Apps that use only Android Views don't require the Gradle plugin for capture. You can continue to declare the appropriate replay runtime artifact directly at version 1.0.0.
Upgrade from the beta
Replace the beta version, including its prerelease suffix, with 1.0.0 in the Gradle plugin declaration and any manually managed replay dependencies. Keep the Gradle plugin applied. Preserve your configuration values and complete the verification steps in this guide.
2. Migrate initialization
Keep your existing Analytics instance, device IDs, and session tracking. Attach only one SessionReplayPlugin to the instance. Pass an Android Context when creating the plugin, and move capture options into SessionReplay.Configuration:
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.SessionReplay
val sessionReplayPlugin = SessionReplayPlugin(
context = applicationContext,
configuration = SessionReplay.Configuration {
sampleRate = 0.1
// Preserve your existing privacy and remote configuration settings.
},
)
amplitude.add(sessionReplayPlugin)
The sample rate is an example. Copy your existing settings instead of adopting the example's rate. Constructors without an Android context no longer work. Version 1.0 deprecates constructors that accept individual capture options; new options use SessionReplay.Configuration.
For standalone integrations, keep identity arguments on SessionReplay and move capture options into the configuration block:
import com.amplitude.android.sessionreplay.SessionReplay
val sessionReplay = SessionReplay(
apiKey = "AMPLITUDE_API_KEY",
context = applicationContext,
deviceId = existingDeviceId,
sessionId = existingSessionId,
configuration = SessionReplay.Configuration {
sampleRate = 0.1
// Preserve your existing privacy, opt-out, and remote configuration settings.
},
)
Supply your existing API key, device ID, and numeric Long session ID. For custom string session IDs, initialize with sessionId = -1L and call setCustomSessionId() with the existing custom ID. Continue updating replay identity and sessions when your analytics integration changes them.
If you wrap an existing client with SessionReplayPlugin(existingSessionReplay), your app remains responsible for that client's identity, sessions, opt-out state, flushing, and shutdown. To let the plugin manage those responsibilities, use the context-and-configuration constructor.
3. Update API calls and imports
Version 1.0 cleans up the public API surface and deprecates some older APIs. If the updated API doesn't cover your use case, contact Amplitude Support or open an issue in AmplitudeSessionReplay-Android.
| API | Migration |
|---|---|
SessionReplay.Configuration.sampleRate | Use a Double, such as 1.0, rather than an integer. |
ServerZone | Import com.amplitude.core.ServerZone when configuring the replay client. |
Logger | Import com.amplitude.common.Logger for custom replay loggers. |
PrivacyConfig | Use a non-null MaskLevel. Prefer PrivacyConfig { maskLevel = MaskLevel.CONSERVATIVE }. Version 1.0 retains the original constructor, copy(), and destructuring for compatibility, but deprecates the constructor and copy(). |
Core SessionReplay.shouldRecord() | Use isRecording(). The old method remains as a deprecated alias. |
getDeviceId() | Handle a nullable result. On a standalone client, setDeviceId(null) stops capture and discards queued replay until you set a device ID again. |
4. Verify capture and privacy
- Rebuild and run the app with the Gradle plugin applied. Resolve any Compose compatibility errors before proceeding.
- Generate a sampled session and navigate through Compose and Android View screens that your app uses.
- Open Session Replay in your Amplitude project and find the test session. Allow time for upload and processing.
- Verify navigation, scrolling, interactions, and session matching with your analytics events.
- Verify masking and blocking on sensitive screens. Compose text masking relies on semantics; use
ampBlock()for sensitive custom drawing or components without those semantics. A child can't override an ancestor'sampBlock(). - Repeat with a release build if you use R8 minification.
If Compose content is missing, confirm that you applied the Gradle plugin in the app module. A declaration with apply false in the root project doesn't enable instrumentation. Adding SessionReplayPlugin at runtime doesn't replace the Gradle plugin.
If no replay appears, check sampling, opt-out state, session IDs, and the API key. Remote configuration defaults to true and can override local sampling and privacy settings. For a local-only test, set enableRemoteConfig = false, then restore your intended production settings.
Was this helpful?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.