Kotlin

Automated

Prefer to automate this? The Appstack CLI detects your project, installs and configures the SDK, then verifies the result:

npx appstack-cli integrate

Already integrated? npx appstack-cli review audits it without changing any files.

AI-assisted

Use Cursor, Claude Code, or another AI to help you integrate the Android (Kotlin) SDK.

Open in Cursor

Repository

Here, you will find the Maven Central Android SDK documentation. Please, use the latest version of the SDK available. Current stable release: 1.11.0, published 16 September 2026. See the changelog for everything that changed.

Quickstart

Use this path when you only need the minimum production integration:

Add the SDK dependency from Maven Central.
Copy the Production API key from SDK in Appstack.
Call AppstackAttributionSdk.configure(...) from Application.onCreate().
Send standard events such as EventType.LOGIN, EventType.SIGN_UP, EventType.PURCHASE, and EventType.SUBSCRIBE.
Confirm events appear in the Appstack SDK page before enabling downstream integrations.

import android.app.Application
import com.appstack.attribution.AppstackAttributionSdk
import com.appstack.attribution.EventType

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        AppstackAttributionSdk.configure(
            context = this,
            apiKey = "your_production_api_key"
        )

        AppstackAttributionSdk.sendEvent(
            EventType.PURCHASE,
            parameters = mapOf("revenue" to 29.99, "currency" to "USD")
        )
    }
}

Watch the video walkthrough

Claude

Codex

AI agent

Manual

Requirements

Minimum SDK: Android 5.0 (API level 21).
Target SDK: 35+
Java Version: 17+
Gradle: 8.0+ (the SDK is built with Gradle 8.13 and Android Gradle Plugin 8.12)

Initial setup

Installation

Add the SDK dependency to your app’s build.gradle.kts:

dependencies {
    // Resolve latest from Maven Central, then prefer pinning an explicit version for release builds.
    implementation("tech.appstack.android-sdk:appstack-android-sdk:+")
}

No additional Gradle configuration is needed after adding the dependency. You still need to initialize the SDK in Application.onCreate() before sending events.

Initialization

Follow these steps to get the API key:

In Appstack, from the side menu, select SDK and ensure you are selecting the correct application.
Select the Production environment.
Copy the API key.

Examples:Configure the SDK in your Application class:

import com.appstack.attribution.AppstackAttributionSdk
import com.appstack.attribution.EventType

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        AppstackAttributionSdk.configure(
            context = this,
            apiKey = "your-android-api-key"
        )
    }
}

Configuration parameters

Initialize the SDK with your API key in Application.onCreate(), before any other SDK methods. configure(...) also takes optional logLevel, listener, and customerUserId parameters; see the Kotlin API reference for the full signature and parameter descriptions.

AppstackAttributionSdk.configure(
    context = this,
    apiKey = "your-api-key"
)

logLevel only controls logcat output (tag AppstackSdk); it does not change what the SDK sends.

Customer user ID

The customer user ID is your own identifier for the signed-in user. Appstack attaches it to events so server-to-server events — which identify the user by this ID rather than by the install — can be joined back to the install that produced them.Set it as soon as it is known — at configure time via the customerUserId parameter, or later, most often once a login reveals it. It applies to every event sent from then on, including any sendEvent buffered during startup, and at least one event has to follow for it to take effect. See setCustomerUserId() in the API reference for the full semantics.

AppstackAttributionSdk.setCustomerUserId("user_123")

Sending events

Track user actions and revenue in your activities:

// Track events without parameters
AppstackAttributionSdk.sendEvent(EventType.SIGN_UP)

// Track events with parameters (including revenue)
AppstackAttributionSdk.sendEvent(
    EventType.PURCHASE,
    parameters = mapOf("revenue" to 29.99, "currency" to "USD")
)

// Custom events
AppstackAttributionSdk.sendEvent(
    EventType.CUSTOM,
    name = "user_attributes",
    parameters = mapOf(
        "email" to "test@example.com",
        "name" to "first_name last_name",
        "phone_number" to "+33060000000",
        "date_of_birth" to "2026-02-01"
    )
)

EventType.INSTALL is tracked automatically on SDK initialization. Do not send it manually. See the Kotlin API reference for the full signature, parameter details, and the complete list of EventType values.Enhanced app campaigns

When running enhanced app campaigns (EACs), it is highly recommended to send multiple parameters with the in-app event to improve matching quality.

For any event that represents revenue, send revenue or price (number) and currency (string, e.g. EUR, USD). To improve matching quality on Meta, also send these when you can:

email.
name (first + last name in the same field).
phone_number — also accepted as phone or phoneNumber.
date_of_birth (recommended format: YYYY-MM-DD) — also accepted as birthdate, birthday, or dateOfBirth.
gender.

Appstack automatically encrypts these matching parameters before using them for attribution matching.

Appstack ID and attribution params

After configure, you can read the Appstack user ID and the attribution map for partner integrations (for example Superwall, RevenueCat).

val appstackId = AppstackAttributionSdk.getAppstackId()

// Inside a coroutine: waits for the initial attribution match to finish
val attributionParams = AppstackAttributionSdk.awaitAttributionParams()

awaitAttributionParams() waits for the initial attribution match, then returns the attribution payload to forward to partners — prefer it over a fixed delay after launch. getAttributionParams() is the non-suspending variant, and both accept an optional raw Play Install Referrer string. See the Kotlin API reference for full signatures and return values. A matched install returns something like:

// {
//   "appstack_adnetwork" to "meta",       // "google", "meta" or "tiktok"
//   "appstack_campaign" to "summer_sale",
//   "appstack_adset" to "lookalike_1pct",
//   "appstack_ad" to "video_15s",
//   "appstack_id" to "9f1c8b64-..."
// }

Android also returns deeplink_id and gclid, and the raw per-network params the click carried. appstack_adnetwork is google, meta or tiktok. It is absent when the click carried no recognised network param — for a standard link, read media_source instead. On Google the campaign, ad set and ad values are numeric IDs rather than names. appstack_id comes back on every result, including organic ones, so use a non-empty deeplink_id as the match check rather than testing whether the map is empty.

The appstack_match_status key that the iOS SDK adds is not reported on Android yet.

Development setup

If you want to test the SDK against the Appstack development environment before shipping, follow these extra steps:

In Appstack, from the side menu, select SDK, switch to the Development environment, and copy the Development API key. This key is separate from your production key.
In your configure(...) call, use the development key and raise the log level:

AppstackAttributionSdk.configure(
    context = this,
    apiKey = "your_development_api_key",
    logLevel = LogLevel.DEBUG
)

The API key is what selects the environment — there is no flag to set. A development key routes to the development environment, a production key to production; both use the same endpoint. On-device diagnostics LogLevel.DEBUG prints the SDK’s initialization, attribution, and event traffic to logcat under the tag AppstackSdk:

adb logcat -s AppstackSdk

Keep the debug log level behind a build-type check so release builds stay quiet:

AppstackAttributionSdk.configure(
    context = this,
    apiKey = "your-api-key",
    logLevel = if (BuildConfig.DEBUG) LogLevel.DEBUG else LogLevel.INFO
)

Security and privacy

Never commit API keys to version control.
Use separate production and development keys, and make sure release builds ship the production key.
Keep LogLevel.DEBUG behind a BuildConfig.DEBUG guard so release builds stay quiet.
Do not put personally identifiable information in event names.
Only send matching parameters such as email, name, phone_number, and date_of_birth when your app has the right consent and compliance basis. Appstack automatically encrypts these fields before using them for attribution matching.
Prefer standard event types for common flows so event mapping remains consistent across Appstack and ad integrations.

Limitations

Platform constraints

Android 5.0+ required (API level 21).
Attribution only works for Play Store installations.
Network connectivity is required at the moment an event is sent. There is no durable offline queue: an event tracked while the device is offline is dropped, not stored for later. Transient failures on a request that did go out (network errors, HTTP 429/500/502/503/504) are retried in-flight with exponential backoff.

Event tracking

The SDK must be initialized in Application.onCreate() before tracking calls.
Custom event names should be descriptive and consistent.
Events sent before the SDK is ready are buffered in memory and replayed once initialization completes.
INSTALL is tracked automatically on SDK initialization. Do not send it manually — the SDK drops such calls.
Revenue events should include revenue or price and currency.

Troubleshooting

Configuration fails

Confirm the API key was copied from the correct app and environment in Appstack.
Confirm the SDK dependency resolves from Maven Central.
Confirm your Application class is registered in AndroidManifest.xml.
Confirm your app declares the INTERNET permission in AndroidManifest.xml — without it configure(...) reports an error through InitListener.onError() and getLastInitError().

Events do not appear

Confirm configure(...) runs in Application.onCreate() before the first sendEvent(...) call.
Confirm the device has network connectivity.
Confirm the app was installed from the Play Store when testing attribution.
Check that revenue events include a numeric revenue or price value and a valid currency.
Allow a few minutes for events to appear in the dashboard.

No SDK logs appear

Confirm configure(...) passes logLevel = LogLevel.DEBUG.
Filter logcat on the SDK tag: adb logcat -s AppstackSdk.

Verification checklist

Dependency installed with tech.appstack.android-sdk:appstack-android-sdk.
App meets min SDK 21, target SDK 35+, Java 17+, and Gradle 8.0+ requirements.
Maven Central is available to Gradle.
Production API key is used in release builds.
Development API key is used only in development builds.
Application class is registered in AndroidManifest.xml.
configure(...) runs once from Application.onCreate().
The customer user ID is set — via configure(...) or setCustomerUserId(...) — as soon as it is known, and at least one event follows it.
INSTALL is not sent manually.
Login, signup, purchase, subscription, and other key app events use standard event types where possible.
Revenue events include revenue or price and currency.
Custom events use EventType.CUSTOM with a descriptive name.
Appstack ID and attribution params are available before wiring partner integrations.
Events are visible in the Appstack SDK page before launch.

Support

For questions or issues:

Check the GitHub Repository.
Contact our support team at support@appstack.tech
Open an issue in the repository.

Use Cursor, Claude Code, or another AI to validate your existing Appstack Android SDK (Kotlin) integration.

Open in Cursor

Getting started

Mobile SDKs

Integrations

Products

Developer tools

Automated

AI-assisted

Repository

Quickstart

Requirements

Initial setup

Appstack ID and attribution params

Development setup

Security and privacy

Limitations

Platform constraints

Event tracking

Troubleshooting

Configuration fails

Events do not appear

No SDK logs appear

Verification checklist

Support

​Automated

​AI-assisted

​Repository

​Quickstart

​Requirements

​Initial setup

​Appstack ID and attribution params

​Development setup

​Security and privacy

​Limitations

​Platform constraints

​Event tracking

​Troubleshooting

​Configuration fails

​Events do not appear

​No SDK logs appear

​Verification checklist

​Support

Automated

AI-assisted

Repository

Quickstart

Requirements

Initial setup

Appstack ID and attribution params

Development setup

Security and privacy

Limitations

Platform constraints

Event tracking

Troubleshooting

Configuration fails

Events do not appear

No SDK logs appear

Verification checklist

Support