Unified SDK for Android

The Amplitude Unified SDK for Android (com.amplitude:unified-android) bundles Analytics, Session Replay, and Experiment into one dependency and initializes them through a single entry point.

Use the Unified SDK when your Android app needs multiple Amplitude products with shared identity and configuration. Install the individual product SDKs instead when your app needs only one product or requires independent SDK instances.

The Unified SDK includes:

• Analytics SDK (Android Kotlin SDK).
• Experiment SDK.
• Session Replay Android Plugin.

Install the SDK

Add the dependency to your build.gradle:

dependencies {
    implementation("com.amplitude:unified-android:1.0.0")
}

The SDK requires:

• minSdk 21 (Android 5.0 Lollipop) or higher.
• compileSdk 35 or higher.
• Kotlin 1.9 or higher.

The Unified SDK transitively includes Analytics (analytics-android 1.33.0), Session Replay 0.31.0, and Experiment 1.17.0. Don't add those SDKs separately.

Initialize the SDK

Initialize the SDK before you instrument. Provide the API key for your Amplitude project.

val amplitude = AmplitudeUnified("API_KEY", applicationContext) {
    analytics {
        // Analytics-specific configuration — refer to the Android Kotlin SDK for all options
    }
    sessionReplay {
        sampleRate = 1.0
    }
    experiment {
        deploymentKey = "DEPLOYMENT_KEY"
    }
}

Configure the SDK

Analytics configuration

The Unified SDK's analytics block accepts the same options as the Android Kotlin SDK's Configuration. For the full option list, refer to the Android Kotlin SDK configuration section.

val amplitude = AmplitudeUnified("API_KEY", applicationContext) {
    analytics {
        flushQueueSize = 30
        flushIntervalMillis = 30000
        minTimeBetweenSessionsMillis = 300000
    }
}

Experiment configuration

Experiment is enabled by default. Setting enabled = false disables Experiment; the experiment accessor then returns null. The deploymentKey defaults to the Analytics API key. The instance name, server zone, user, and exposure tracking all come from Analytics.

val amplitude = AmplitudeUnified("API_KEY", applicationContext) {
    experiment {
        deploymentKey = "DEPLOYMENT_KEY"
        config = ExperimentConfig()
    }
}

Session Replay configuration

Session Replay is enabled by default with a sampleRate of 0.0, so nothing records until you set the sample rate. Setting enabled = false disables Session Replay; the sessionReplay accessor then returns null. For advanced configuration options, refer to the Session Replay Android Plugin documentation.

val amplitude = AmplitudeUnified("API_KEY", applicationContext) {
    sessionReplay {
        sampleRate = 1.0
        enableRemoteConfig = true
    }
}

Use the SDK

AmplitudeUnified is the Analytics client and exposes the full Android Kotlin SDK API. It adds sessionReplay and experiment accessors, both nullable.

Analytics

// Track an event
amplitude.track("Button Clicked", mapOf("button_id" to "sign_up"))

// Set user properties
val identify = Identify()
identify.set("plan", "premium")
amplitude.identify(identify)

// Set user ID
amplitude.setUserId("user@example.com")

Experiment

AmplitudeUnified initializes and configures the Experiment client when you create an instance. Access the client through the experiment property. Exposures track through Analytics. When Session Replay is recording and its device and session IDs match the event, the Session Replay plugin enriches the exposure event with [Amplitude] Session Replay ID.

val client = amplitude.experiment ?: return

// Fetch variants for the current user
client.fetch().get()

// Get a variant for a flag
val variant = client.variant("my-flag")
if (variant.value == "on") {
    // Flag is on
}

Session Replay

AmplitudeUnified initializes and configures Session Replay when you create an instance. Access the client through the sessionReplay property. Session Replay uses the Analytics device and session IDs; it doesn't store a user ID.

// Session Replay is automatically initialized and configured.

// Start (or resume) capture
amplitude.sessionReplay?.start()

// Stop (pause) capture. Call start() again to resume.
amplitude.sessionReplay?.stop()

Identity management

AmplitudeUnified synchronizes user identity across all Amplitude products. Identity and lifecycle changes forward to the owned plugins automatically:

• User ID changes update Experiment.
• Device ID, reset, opt-out, and session changes synchronize with Session Replay and Experiment.
• Session Replay uses the Analytics device and session IDs; it doesn't store a user ID.

// Propagates to all products
amplitude.setUserId("user@example.com")

// Propagates to all products
amplitude.setDeviceId("custom-device-id")

// Clears user ID and generates a new device ID
amplitude.reset()

Debugging

To enable debug logging, set the log mode on the initialized instance:

val amplitude = AmplitudeUnified("API_KEY", applicationContext)
amplitude.logger.logMode = Logger.LogMode.DEBUG

Common issues

R8 reports missing optional provider classes

If R8 reports missing org.conscrypt, org.bouncycastle, or org.openjsse classes, add:

implementation("com.squareup.okhttp3:okhttp:4.12.0")

Experiment 1.17.0 bundles OkHttp 4.9.1, which doesn't include R8 rules for optional TLS providers. OkHttp 4.12.0 adds those rules.

Kotlin reports Cannot access 'CoroutineScope'

If Kotlin reports Cannot access 'CoroutineScope' when you call Session Replay members, add:

implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")

Migration guide

If you use the individual Amplitude SDKs separately, follow these steps to migrate to the Unified SDK.

1. Replace the individual SDK dependencies with the Unified SDK in build.gradle.
2. Remove individual plugin registration and initialization code.
3. Replace your initialization code with Unified SDK initialization.

Before migration

// Analytics SDK
val amplitude = Amplitude(
    Configuration(
        apiKey = "API_KEY",
        context = applicationContext,
    )
)

// Session Replay plugin
val sessionReplayPlugin = SessionReplayPlugin(context = applicationContext, sampleRate = 1.0)
amplitude.add(sessionReplayPlugin)

// Experiment SDK
val client = Experiment.initializeWithAmplitudeAnalytics(
    applicationContext, "DEPLOYMENT_KEY", ExperimentConfig()
)
client.fetch().get()

After migration

val amplitude = AmplitudeUnified("API_KEY", applicationContext) {
    sessionReplay {
        sampleRate = 1.0
    }
    experiment {
        deploymentKey = "DEPLOYMENT_KEY"
    }
}

amplitude.experiment?.fetch()?.get()