---
title: "Get started with the Android-Kotlin SDK"
description: "Install the Amplitude Android-Kotlin SDK, initialize it in your Application class, send a first event, and fix the Android problems that stop events from arriving."
product: analytics
lang: en
last_updated: 2026-11-04
token_estimate: 2550
---
# Get started with the Android-Kotlin SDK

- **Package:** `com.amplitude:analytics-android` ([maven](https://search.maven.org/artifact/com.amplitude/analytics-android))
- **Latest version:** 1.37.0

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](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/reference#configuration-options). For changes between versions, go to the [Android-Kotlin SDK release notes](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk-release-notes).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

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](https://amplitude.com/docs/sdks/analytics/android/unified-sdk/get-started) (`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](https://amplitude.com/docs/sdks/analytics/android/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.

#### Kotlin DSL

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

#### Groovy

```groovy
dependencies {
    implementation 'com.amplitude:analytics-android:1.37.0'
}
```

#### Maven

```xml
<dependency>
    <groupId>com.amplitude</groupId>
    <artifactId>analytics-android</artifactId>
    <version>1.37.0</version>
</dependency>
```

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.

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

### Fix installation problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Logcat warning: `No ACCESS_NETWORK_STATE permission, offline mode is not supported. ...` | The app doesn't declare `ACCESS_NETWORK_STATE`. | Add the permission if you want offline support. Without it, the SDK treats the device as always online. |
| Logcat error: `Request failed: java.lang.SecurityException: ...` | The app doesn't declare `INTERNET`. | Add `<uses-permission android:name="android.permission.INTERNET" />`. |

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

#### Kotlin

```kotlin
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
    }
}
```

#### Java

```java
import android.app.Application;
import com.amplitude.android.Amplitude;
import com.amplitude.android.ConfigurationBuilder;

public class MyApplication extends Application {
    public static Amplitude amplitude;

    @Override
    public void onCreate() {
        super.onCreate();
        ConfigurationBuilder builder =
            new ConfigurationBuilder("YOUR_API_KEY", getApplicationContext());
        // Set options here, for example builder.setServerZone(ServerZone.EU);
        amplitude = new Amplitude(builder.build());
    }
}
```

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

| Symptom | Cause | Fix |
| --- | --- | --- |
| `java.lang.ClassCastException` naming `android.app.Application` | You passed an `Activity` or other non-application context. | Pass `applicationContext` (Kotlin) or `getApplicationContext()` (Java). |
| `java.lang.IllegalArgumentException: invalid configuration` | The API key is blank, or `flushQueueSize`, `flushIntervalMillis`, or `minIdLength` is 0 or less. | Check the variable that holds your key. Build configurations often inject an empty value when a property is missing. |
| Logcat warning: `Amplitude instance '<name>' was replaced by a newer instance with the same name and is now inactive.` | Your code created a second instance with the same `instanceName`, for example in an `Activity`. The older instance drops new events. | Create one instance in `Application.onCreate` and reuse it. Go to [Run more than one instance](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/instrument-and-configure#run-more-than-one-instance). |
| `getDeviceId()` returns `null` | The SDK hasn't finished loading stored identity. | Call `amplitude.isBuilt.await()` in a coroutine before you read the device ID. |
| No screen views or app lifecycle events | The default `autocapture` set contains only `SESSIONS`. | Add the features you want. Go to [Autocapture](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/instrument-and-configure#autocapture). |

## Send a first event

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

#### Kotlin

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

#### Java

```java
Map<String, Object> properties = new HashMap<>();
properties.put("plan", "starter");
amplitude.track("Sign Up Clicked", properties);
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`:

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

| Logcat message | Cause | Fix |
| --- | --- | --- |
| `Skip event for opt out config.` | Opt-out is on. The SDK drops every event. | Set `amplitude.optOut = false`, or remove `optOut = true` from your configuration. |
| `Event has an empty event type, dropping it.` | The event name is empty. | Pass a non-empty event name. |
| `Handle response, status: BAD_REQUEST, error: Invalid API key: ...`, then `Invalid API key. Don't retry.` | The key is wrong, or belongs to a project in the other data center. The SDK deletes the events. | Copy the key again and check `serverZone`. |
| `Handle response, status: FAILED, error: ...`, repeating | The server returned an error, or a proxy at `serverUrl` returned a status other than 2xx, 400, 408, 413, or 429. The SDK keeps the events and retries with backoff, up to every 5 minutes. | Check the request host and status. Go to [Check what the SDK sent](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/verify-events#check-what-the-sdk-sent). |
| `Request failed: java.net.UnknownHostException: ...` or another `Request failed:` line | The request didn't reach the server: no network, a DNS failure, a blocked host, or a missing `INTERNET` permission. The SDK keeps the events and retries. | Check connectivity from the device. If a firewall or network blocks Amplitude, route events through a [proxy](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/instrument-and-configure#send-events-through-a-proxy). |
| No `Handle response` line | The upload hasn't happened yet, or the device is offline. | Call `amplitude.flush()`. Check that the device is online. |

## 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](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/verify-events). That page walks through each stage between `track()` and Amplitude's servers.

## Next steps

- Identify signed-in users with [`setUserId()`](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/instrument-and-configure#set-the-user-id), and call `reset()` when they sign out.
- Choose which [Autocapture](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/instrument-and-configure#autocapture) events to collect.
- Add the custom events and properties your tracking plan needs. Go to [Track events](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/instrument-and-configure#track-events).