> For the complete documentation index, see [llms.txt](https://docs.amply.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amply.tools/developer-guide/quickstart-android.md).

# Quickstart — Android

Install the Amply Android SDK, initialize it with your API keys, and send your first event. You'll end with a tracked event visible in the Amply dashboard.

This tutorial takes about ten minutes. It uses Kotlin and initializes the SDK in your `Application` class, which is the recommended entry point because it fires before any `Activity` starts.

**Prerequisites**

* A minSdk of 21 (Android 5.0) or higher — see [Installation](/developer-guide/installation.md) for the full requirements matrix
* An Amply dashboard account with `appId`, `apiKeyPublic`, and `apiKeySecret` (Settings → API Keys)
* Gradle configured to resolve from `mavenCentral()`

**You'll end with**

* The SDK initialized on app startup
* One custom event tracked from your code
* That event showing up in the Amply dashboard's event log

## 1. Add the SDK

Follow [Installation → Android](/developer-guide/installation.md) to add `tools.amply:sdk-android` to your app module's dependencies (see [Installation — Current versions](/developer-guide/installation.md#current-versions) for the version to pin). Come back here once your build resolves.

## 2. Create (or open) your Application class

If your project already has a custom `Application`, open it. If not, create one next to your `MainActivity`:

{% code title="app/src/main/java/com/acme/app/AmplyApp.kt" %}

```kotlin
package com.acme.app

import android.app.Application
import tools.amply.sdk.Amply
import tools.amply.sdk.config.amplyConfig

class AmplyApp : Application() {

    lateinit var amply: Amply
        private set

    override fun onCreate() {
        super.onCreate()

        val config = amplyConfig {
            api {
                appId = "com.acme.app"
                apiKeyPublic = "YOUR_PUBLIC_KEY"
                apiKeySecret = "YOUR_SECRET_KEY"
            }
        }

        amply = Amply(config, this)
    }
}
```

{% endcode %}

Register it in `AndroidManifest.xml`:

```xml
<application
    android:name=".AmplyApp"
    ... >
```

Constructing `Amply(config, this)` starts the SDK. There's no separate `initialize()` call. The `Application` instance is required so the SDK can observe the process lifecycle automatically (see step 4).

{% hint style="info" %}
The `amplyConfig { api { ... } }` DSL is the recommended way to build `AmplyConfig` — it's declarative and keeps credentials grouped.
{% endhint %}

## 3. Track your first event

From anywhere with access to the `Application` (or a DI-provided `Amply` instance), call `track`:

```kotlin
val amply = (application as AmplyApp).amply
amply.track(event = "Signup", properties = mapOf("plan" to "pro"))
```

`track(event, properties)` takes an event name and an optional `Map<String, Any>` of properties. Names should be short and consistent (e.g., `Signup`, `Purchase`, `TrialStarted`). Supported property value types: `String`, `Int`, `Long`, `Float`, `Double`, `Boolean`, `DateTimeValue`.

From a `ViewModel` or `Activity`, inject the SDK instance rather than reaching through `application` — the approach above is just the shortest path to a first event.

## 4. Session lifecycle (nothing to do)

On Android the SDK observes `ProcessLifecycleOwner` and manages sessions automatically:

* A session starts the first time your process becomes foreground.
* It pauses when the app goes to background and resumes when the user returns.
* It ends after the configured inactivity timeout.

You don't call `pauseSession()`, `resumeSession()`, or `stopSession()` on Android. (Those methods exist on iOS because UIKit doesn't give the SDK a process-level lifecycle hook.)

## 5. Turn on logs while you verify

Before shipping, lower the log level. While wiring things up, turn it up:

```kotlin
amply.setLogLevel("debug")
```

SDK output lands in Logcat under tags starting with `Amply`. Use the Logcat filter `tag:Amply` to see only SDK messages.

Valid levels: `"none"`, `"error"`, `"warn"`, `"info"`, `"debug"`.

## 6. Verify in the dashboard

1. Run the app on an emulator or device.
2. Trigger the code path that calls `track(event = "Signup", ...)`.
3. Open the Amply dashboard and go to **Events** (or the real-time event log for your app).
4. You should see a `signup` entry with `plan: pro` within a few seconds.

If nothing shows up:

* Filter Logcat on `tag:Amply` and look for error lines
* Confirm the values in `amplyConfig { api { ... } }` match the dashboard Settings → API Keys page exactly
* Confirm the device has internet — the first event needs a successful round-trip to prove the pipeline works

## What's next

* [Android integration](/developer-guide/android-integration.md) — deep links, custom properties, user IDs, ProGuard notes
* [Concepts → Sessions and events](/concepts/sessions-and-events.md) — how events, properties, and datasets fit together
* [Recipes — entry-based onboarding routing](/recipes/entry-based-onboarding-routing.md) — ready-made pattern for signup and onboarding flows

## Related

* [Installation](/developer-guide/installation.md) — Gradle coordinates, minimum versions, permissions
* [iOS Quickstart](/developer-guide/quickstart-ios.md) — same flow on iOS (note: iOS requires manual session calls)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amply.tools/developer-guide/quickstart-android.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.