Kotlin

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

Repository

Here, you will find the Maven Central Android SDK documentation. Please, use the latest version of the SDK available.

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")
        )
    }
}

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. Must be called in Application.onCreate() before any other SDK methods.

Parameters:

context (Context, required): Application context.
apiKey (String, required): Your Appstack API key.
logLevel (LogLevel, default: LogLevel.INFO): Console log verbosity. One of DEBUG, INFO, WARN, ERROR, NONE.
listener (InitListener?, default: null): Optional callback invoked on initialization success or error.
customerUserId (String?, default: null): Your own user identifier, attached to the event payload.

Examples:

// Minimum configuration — context and the API key are the only required parameters
AppstackAttributionSdk.configure(
    context = this,
    apiKey = "your-api-key"
)

// With optional parameters
AppstackAttributionSdk.configure(
    context = this,
    apiKey = "your-api-key",
    logLevel = LogLevel.INFO,
    customerUserId = "user_123"
)

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

Sending events

Track user actions and revenue in your activities:

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

// 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"
    )
)

Available EventType valuesIt is recommended to use standard events for a smoother experience.

EventType.INSTALL is tracked automatically on SDK initialization. Do not send it manually.

EventType.LOGIN User login.
EventType.SIGN_UP / EventType.REGISTER User registration.
EventType.PURCHASE Purchase transactions.
EventType.SUBSCRIBE Subscription events.
EventType.ADD_TO_CART, EventType.ADD_TO_WISHLIST, EventType.INITIATE_CHECKOUT E-commerce events.
EventType.START_TRIAL Trial start.
EventType.LEVEL_START/ EventType.LEVEL_COMPLETE Game progression.
EventType.TUTORIAL_COMPLETE, EventType.SEARCH, EventType.VIEW_ITEM, EventType.VIEW_CONTENT, EventType.SHARE Engagement events.
EventType.CUSTOM For any other custom events.

Tracks custom events with optional parameters:

event Event type from EventType enum (required).
name Event name for custom events (optional, required when event is CUSTOM).
parameters - Optional map of parameters (e.g., mapOf("revenue" to 29.99, "currency" to "USD")).

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, we recommend sending:

revenue or price (number).
currency (string, e.g. EUR, USD).

AppstackAttributionSdk.sendEvent(
    EventType.PURCHASE,
    parameters = mapOf("revenue" to 4.99, "currency" to "EUR")
)

To improve matching quality on Meta, send events including the following parameters if you can fulfill them. Appstack automatically encrypts these matching parameters before using them for attribution matching.

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

getAppstackId() — Appstack user identifier when a partner expects $appstackId or similar.
awaitAttributionParams() — suspend function that waits for the initial attribution match, then returns the attribution payload (campaign, media source, click IDs, device identifiers where available) to forward to partners. Prefer this over a fixed delay after launch.
getAttributionParams() — Non-suspending variant that returns whatever is cached right now. Called immediately after configure(...) it can still be empty, because the match runs asynchronously.

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.

Superwall

To start using the Superwall integration, click here to see the correct SDK documentation.

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

API reference

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

Superwall

Verification checklist

Support

​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

​Superwall

​Verification checklist

​Support

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

Superwall

Verification checklist

Support