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.0 or 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.9 or later (tested through 1.13.0-beta01).
  • Android Gradle Plugin (AGP) 8.5 or later.
  • JDK 17 or 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:

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:

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

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

4. Verify capture and privacy

  1. Rebuild and run the app with the Gradle plugin applied. Resolve any Compose compatibility errors before proceeding.
  2. Generate a sampled session and navigate through Compose and Android View screens that your app uses.
  3. Open Session Replay in your Amplitude project and find the test session. Allow time for upload and processing.
  4. Verify navigation, scrolling, interactions, and session matching with your analytics events.
  5. 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's ampBlock().
  6. 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.

これは役に立ちましたか?

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.

このページでは