Get started with the Android-Kotlin SDK

This guide helps you install the Android-Kotlin SDK (com.amplitude:analytics-android), initialize it, and send one custom event to Amplitude. Each step lists the conditions that commonly break that step, so you can fix a problem where it happens. For the full option list, go to Configuration options. For changes between versions, go to the Android-Kotlin SDK release notes.

The Android-Kotlin SDK is the analytics-only package and works with Kotlin and Java. If you also need Session Replay or Feature Experiment, install the Unified SDK for Android (com.amplitude:unified-android) instead. The Unified SDK includes the Android-Kotlin SDK, so don't add both. If your app still uses the maintenance Android SDK (com.amplitude:android-sdk), go to Migrate to the Android-Kotlin SDK.

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.
• The INTERNET permission in your app's AndroidManifest.xml. The SDK's own manifest declares no permissions.

Install the SDK

Add the dependency to your module's build file, then sync the project.

dependencies {
    implementation("com.amplitude:analytics-android:1.37.0")
}

Then add the permissions to AndroidManifest.xml. ACCESS_NETWORK_STATE is optional. That permission lets the SDK hold events while the device is offline and upload them when it reconnects.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Fix installation problems

Initialize the SDK

Create the instance once, in Application.onCreate, so autocapture sees the whole app lifecycle. Pass the application context, then reuse the instance everywhere.

import android.app.Application
import com.amplitude.android.Amplitude

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        amplitude = Amplitude("YOUR_API_KEY", applicationContext) {
            // Set options here, for example serverZone = ServerZone.EU
        }
    }

    companion object {
        lateinit var amplitude: Amplitude
    }
}

Register the class in AndroidManifest.xml with <application android:name=".MyApplication" ...>.

If your project uses the EU data center, set serverZone = ServerZone.EU (import com.amplitude.core.ServerZone). In Java, build options with ConfigurationBuilder, which requires 1.27.0 or later. Don't use new Configuration(apiKey, context) from Java: it calls a deprecated constructor that can't set newer options such as autocapture.

The constructor returns immediately and finishes loading stored identity in the background. You can track events right away. The SDK queues them until setup finishes. To read a stored value, such as the device ID, wait for amplitude.isBuilt.await() in a coroutine first.

Fix initialization problems

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()

Without flush(), the SDK uploads 30 seconds after the first queued event or as soon as the queue holds 30 events. It also uploads when the app goes to the background.

To see the upload result for each event, turn on debug logging and filter Logcat on the tag Amplitude:

amplitude.logger.logMode = Logger.LogMode.DEBUG // import com.amplitude.common.Logger

A successful upload logs Logged event with type: Sign Up Clicked, then Handle response, status: SUCCESS.

Fix upload problems

Confirm the event in Amplitude

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

If the event doesn't appear within a minute, follow Verify events. That page walks through each stage between track() and Amplitude's servers.

Next steps

• Identify signed-in users with setUserId(), and call reset() when they sign out.
• Choose which Autocapture events to collect.
• Add the custom events and properties your tracking plan needs. Go to Track events.