Get started with the Unified SDK for Android

mavenv1.1.0

For Android developers10 minBeginner

This guide helps you install the Unified SDK for Android (com.amplitude:unified-android), initialize every product it includes with one constructor, and send one custom event to Amplitude. For the full option list, go to UnifiedConfigurationBuilder. For changes between versions, go to the Unified SDK changelog.

The Unified SDK bundles the Android-Kotlin SDK (com.amplitude:analytics-android) with the Session Replay Android plugin and the Experiment Android SDK. AmplitudeUnified extends the Android-Kotlin SDK's Amplitude class, so every analytics method and option works the same. If you need Analytics only, install the Android-Kotlin SDK instead. Don't add both SDKs, or the separate Session Replay and Experiment SDKs, to the same app.

Prerequisites

An Amplitude project and its API key. To find the key, go to Settings > Projects, select your project, and open General.
The data center your organization uses: US (default) or EU.
An app with minSdk 21 (Android 5.0) or later, built with compileSdk 35 or later.

Install the SDK

Add the dependency to your module's build file (build.gradle.kts or build.gradle), then sync the project:

kotlin

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

The dependency brings in Analytics, Session Replay, and Experiment. If your app already declares any of those SDKs separately, remove them. Gradle resolves each SDK to one version without a warning, and that version can differ from the version the Unified SDK was built with. Version 1.1.0 includes analytics-android 1.36.0, plugin-session-replay-android 0.31.0, and experiment-android-client 1.18.0.

Fix installation problems

Symptom	Cause	Fix
R8 reports missing `org.conscrypt`, `org.bouncycastle`, or `org.openjsse` classes	Experiment 1.18.0 depends on OkHttp 4.9.1, which doesn't ship R8 rules for optional TLS providers.	Add `implementation("com.squareup.okhttp3:okhttp:4.12.0")`. OkHttp 4.12.0 includes those rules.
Kotlin reports `Cannot access 'CoroutineScope'` when you call Session Replay members	The Session Replay API exposes a coroutines type that isn't on your compile classpath.	Add `implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")`.

Initialize the SDK

Create one AmplitudeUnified instance per process, in Application.onCreate, and reuse it. Pass the application context. The constructor builds Analytics, then installs Session Replay, then Experiment.

import com.amplitude.unified.AmplitudeUnified

val amplitude = AmplitudeUnified("YOUR_API_KEY", applicationContext) {
    analytics {
        // Android-Kotlin SDK options, for example serverZone = ServerZone.EU
    }
    sessionReplay {
        sampleRate = 1.0 // Records every session. Lower this before production.
    }
}

Session Replay records nothing until you set sampleRate above 0.0. Experiment uses your Analytics API key as its deployment key unless you set experiment { deploymentKey = "..." }.

Fix initialization problems

Symptom	Cause	Fix
Log: `Failed to install plugin "<name>": <exception>`	Session Replay or Experiment threw during setup. The SDK skips that product and keeps Analytics and the other product running.	Read the exception in the log. The accessor for the skipped product (`sessionReplay` or `experiment`) returns `null`.
`amplitude.experiment` returns `null` with Experiment enabled	The app also adds its own `AmplitudeExperimentPlugin`, so the instance holds more than one Experiment client and the accessor can't pick one.	Remove your own Experiment plugin and any `Experiment.initializeWithAmplitudeAnalytics()` call. Go to Migrate from separate SDKs.
No replays	`sessionReplay.sampleRate` is `0.0`, the default.	Set `sampleRate` above `0.0`.
No variants, or variants for the wrong project	Experiment uses the Analytics API key, but your flags belong to a deployment with a different key.	Set `experiment { deploymentKey = "YOUR_DEPLOYMENT_KEY" }`.

For analytics initialization problems, go to Fix initialization problems in the Android-Kotlin SDK.

Send a first event

Track one custom event, then flush so you don't wait for the upload interval:

amplitude.track("Sign Up Clicked", mapOf("plan" to "starter"))
amplitude.flush()

Fix upload problems

The Unified SDK uploads events through the bundled Android-Kotlin SDK, so upload behavior and log messages match the Android-Kotlin SDK. Go to Fix upload problems in the Android-Kotlin SDK.

Confirm the event in Amplitude

In Amplitude, open User Lookup and search for the device ID from amplitude.getDeviceId().
Open the Activity tab and turn on Live event updates.
Confirm that Sign Up Clicked appears with the plan property.

If the event doesn't appear within a minute, follow Verify events.

Next steps

Set options for each product. Go to Configure each product.
Read flag variants. Go to Use Feature Experiment.
Replace separate Analytics, Session Replay, and Experiment setup. Go to Migrate from separate SDKs.
Track custom events, identify users, and choose autocapture events. Go to the Instrument and configure the Android-Kotlin SDK.

Was this helpful?