Instrument and configure the Unified SDK for Android

This guide covers the work specific to the Unified SDK for Android after Get started: configuring each product, using Feature Experiment and Session Replay, sharing identity, and migrating from separate SDKs. For tracking events, identity, sessions, autocapture, and data delivery, use the Instrument and configure the Android-Kotlin SDK. AmplitudeUnified has every method that guide describes. For signatures and defaults, go to the Reference. For changes between versions, go to the Unified SDK changelog.

Configure each product

How the Unified SDK sets up each product

When you construct AmplitudeUnified, the SDK:

1. Builds Analytics from the analytics options, exactly as the Android-Kotlin SDK's Amplitude constructor does.
2. Installs Session Replay as a plugin, unless sessionReplay.enabled is false. Session Replay records against the Analytics API key, server zone, device ID, and session ID.
3. Installs Experiment as a plugin, unless experiment.enabled is false. Experiment takes its instance name, server zone, user, and exposure tracking from Analytics, and uses the Analytics API key unless you set deploymentKey.
4. Adds amplitude-android-unified/<version> to the front of each event's library value.

If Session Replay or Experiment throws during setup, the SDK logs Failed to install plugin "<name>": <exception> and keeps the rest running.

Pass options to each product

Each product has its own block. The analytics block is the Android-Kotlin SDK's ConfigurationBuilder, so it takes every Android-Kotlin SDK configuration option.

import com.amplitude.core.ServerZone
import com.amplitude.unified.AmplitudeUnified

val amplitude = AmplitudeUnified("YOUR_API_KEY", applicationContext) {
    analytics {
        serverZone = ServerZone.EU
        flushQueueSize = 20
        minTimeBetweenSessionsMillis = 300_000
    }
    sessionReplay {
        sampleRate = 0.1
    }
    experiment {
        deploymentKey = "YOUR_DEPLOYMENT_KEY"
    }
}

Set serverZone in analytics. Session Replay and Experiment read it from Analytics, so you set it once.

Turn off a product

Set enabled = false in the product's block. The SDK doesn't install that product, and its accessor returns null.

val amplitude = AmplitudeUnified("YOUR_API_KEY", applicationContext) {
    sessionReplay { enabled = false }
}

Use Feature Experiment

Fetch flags and read a variant

Read the client from amplitude.experiment. You don't need to call start(). The SDK starts the client as soon as three conditions are true: Analytics has a device ID, Analytics has a session ID, and the user isn't opted out. Because fetchOnStart defaults to true, the client fetches flags when it starts.

val experiment = amplitude.experiment ?: return

val variant = experiment.variant("checkout-redesign")
if (variant.value == "treatment") {
    // Show the new checkout.
}

variant() reads cached variants, so a call made before the first fetch finishes returns the fallback. To wait for fresh variants, for example right after sign-in, call fetch() and wait for its Future. Call get() off the main thread:

experiment.fetch().get()

Exposures go through Analytics as $exposure events, so they use the same identity, queue, and upload settings as your other events.

The Unified SDK keeps Experiment in step with Analytics:

• Identity changes: The SDK updates the Experiment user when the user ID, device ID, or user properties change. The SDK refetches flags only when you build the config with .automaticFetchOnAmplitudeIdentityChange(true) (default false).
• Opt-out: When you set optOut = true, the SDK stops flag polling. variant() still returns cached variants. When you opt back in, the SDK restarts the client.
• Reset: reset() clears cached variants.

Set the deployment key

Experiment uses your Analytics API key unless you set a deployment key. Set one when your flags belong to a deployment with its own key:

val amplitude = AmplitudeUnified("YOUR_API_KEY", applicationContext) {
    experiment {
        deploymentKey = "YOUR_DEPLOYMENT_KEY"
    }
}

For other Experiment options, build a config with ExperimentConfig.builder() and set experiment { config = ... }. The SDK replaces instanceName and serverZone in that config with the Analytics values. Go to the Experiment Android SDK.

Use Session Replay

Choose a sample rate

sampleRate defaults to 0.0, which records nothing. Set it to the fraction of sessions to record, from 0.0 to 1.0. Use 1.0 while you test, then lower it.

Control recording from code

Read the client from amplitude.sessionReplay. Call stop() to pause capture, for example on a screen that shows sensitive data, and start() to resume.

amplitude.sessionReplay?.stop()
// ...
amplitude.sessionReplay?.start()

To choose when capture first starts, set sessionReplay { autoStart = false } and call start() yourself.

While Session Replay records, the plugin adds [Amplitude] Session Replay ID to each event whose device ID and session ID match the recording, including Experiment exposures. Charts use that property to link events to replays.

For masking, WebView capture, and log recording, go to the Session Replay Android plugin.

Share identity across products

setUserId(), setDeviceId(), reset(), opt-out, and session changes on AmplitudeUnified reach Session Replay and Experiment automatically. Go to Identity and sessions in the Android-Kotlin SDK.

To change the user ID, device ID, and user properties in one step, call setIdentity(). The SDK passes the new identity to Experiment as one update, so the Experiment user carries the new properties on its next fetch. Read the device ID after Analytics finishes loading stored identity:

import com.amplitude.core.events.Identify

// Inside a coroutine
amplitude.isBuilt.await()
val deviceId = requireNotNull(amplitude.getDeviceId())
amplitude.setIdentity("user-123", deviceId, mapOf("plan" to "paid"))

setIdentity() replaces both IDs and the user properties together. The properties live in memory for the current process. The SDK doesn't persist them. If you omit the properties argument, setIdentity() clears the user properties. To remove a user property in Amplitude, send an identify: amplitude.identify(Identify().unset("plan")). Shared identity requires Unified SDK 1.1.0 or later.

Migrate from separate SDKs

If your app sets up the Android-Kotlin SDK, the Session Replay plugin, and Experiment separately, replace that setup with one AmplitudeUnified.

1. In your module's build file, replace analytics-android, plugin-session-replay-android, and experiment-android-client with unified-android.
2. Remove the SessionReplayPlugin registration and the Experiment client setup.
3. Replace the Amplitude constructor with AmplitudeUnified, moving each product's options into its block.

Before:

val amplitude = Amplitude("YOUR_API_KEY", applicationContext) {
    flushQueueSize = 20
}
amplitude.add(SessionReplayPlugin(applicationContext, sampleRate = 1.0))

val experiment = Experiment.initializeWithAmplitudeAnalytics(
    applicationContext, "YOUR_DEPLOYMENT_KEY", ExperimentConfig()
)
experiment.fetch().get()

After:

val amplitude = AmplitudeUnified("YOUR_API_KEY", applicationContext) {
    analytics { flushQueueSize = 20 }
    sessionReplay { sampleRate = 1.0 }
    experiment { deploymentKey = "YOUR_DEPLOYMENT_KEY" }
}

val experiment = amplitude.experiment

Keep the same instanceName (or leave it unset in both), so the Unified SDK reads the identity and queued events the separate SDK stored.