> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appstack.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Kotlin
You are an expert Android engineer helping me integrate the Appstack Android SDK (Kotlin) into my app. You are running inside an IDE assistant such as Cursor or Claude Code and you can see my codebase.
Use the reference below to fully wire the SDK. When I share my Gradle files and app code, you should:
1. Propose **exact Gradle changes** (repositories and `dependencies { ... }`) using the dependency coordinates below and the **current** artifact version from Maven Central.
2. Tell me exactly where to initialize the SDK (Application.onCreate) and generate idiomatic Kotlin code that matches my app's structure, using the snippets below.
3. Wire all documented configuration options (debug, log level, endpoint overrides) when relevant.
4. Validate min/target SDK, Java/Gradle versions and any manifest or ProGuard/R8 needs against the requirements below, and point out gaps.
5. Summarize the full set of steps (install, configure, event tracking) so I can verify everything has been applied.
***
## Reference: Appstack Android SDK (Kotlin)
**Requirements**
* Min SDK: Android 5.0 (API 21), Target SDK: 34+, Java 8+, Gradle 7.0+
* SDK artifact: [Maven Central](https://central.sonatype.com/artifact/tech.appstack.android-sdk/appstack-android-sdk) — use latest version.
**1. Gradle dependency**
```kotlin theme={null}
dependencies {
// Resolve the latest from Maven Central, then pin an explicit version for reproducible builds.
implementation("tech.appstack.android-sdk:appstack-android-sdk:+")
}
```
Prefer copying a **specific** version from the Maven Central page linked above once you know what you want to ship; avoid leaving `+` in production if your team requires locked versions.
**2. Initialize in Application.onCreate**
```kotlin theme={null}
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"
)
}
}
```
**3. Full configuration (optional params)**
```kotlin theme={null}
AppstackAttributionSdk.configure(
context = this,
apiKey = "your-api-key",
isDebug = BuildConfig.DEBUG,
logLevel = LogLevel.INFO
)
```
* Optional: `endpointBaseUrl` for custom endpoint.
* Debug overlay (only when isDebug = true):
```kotlin theme={null}
if (BuildConfig.DEBUG) {
AppstackAttributionSdk.showDebugOverlay(this)
}
```
**4. Event tracking**
* Simple events:
```kotlin theme={null}
AppstackAttributionSdk.sendEvent(EventType.SIGN_UP)
AppstackAttributionSdk.sendEvent(EventType.LOGIN)
```
* With parameters (e.g. revenue):
```kotlin theme={null}
AppstackAttributionSdk.sendEvent(
EventType.PURCHASE,
parameters = mapOf("revenue" to 29.99, "currency" to "USD")
)
```
* Custom events:
```kotlin theme={null}
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 values (use standard when possible):** LOGIN, SIGN\_UP/REGISTER, PURCHASE, SUBSCRIBE, ADD\_TO\_WISHLIST, INITIATE\_CHECKOUT, START\_TRIAL, LEVEL\_START, LEVEL\_COMPLETE, TUTORIAL\_COMPLETE, SEARCH, SHARE, CUSTOM.
**Revenue / EAC:** For revenue events send `revenue` or `price` (number) and `currency` (string). For better Meta matching, include when possible: `email`, `name`, `phone_number`, `date_of_birth` (YYYY-MM-DD).
**Limitations:** Init must happen in Application.onCreate before any tracking. Debug overlay only when isDebug = true. Attribution for Play Store installs; network required (offline queueing supported).
## **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).
```kotlin theme={null}
val appstackId = AppstackAttributionSdk.getAppstackId()
val attributionParams = AppstackAttributionSdk.getAttributionParams()
```
* **`getAppstackId()`** — Appstack user identifier when a partner expects `$appstackId` or similar.
* **`getAttributionParams()`** — Attribution payload (campaign, media source, click IDs, device identifiers where available) to forward to partners.
### **Maven Central repository**
Here, you will find the [Maven Central Android SDK documentation](https://central.sonatype.com/artifact/tech.appstack.android-sdk/appstack-android-sdk). Please, use the latest version of the SDK available.
### **Requirements**
1. Minimum SDK: Android 5.0 (API level 21).
2. Target SDK: 34+
3. Java Version: 8+
4. Gradle: 7.0+
## **Initial setup**
Add the SDK dependency to your app's `build.gradle.kts`:
```kotlin theme={null}
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 configuration needed - the SDK will work automatically after installation.
Follow these steps to get the API key:
1. In Appstack, from the side menu, select **SDK** and ensure you are selecting the correct application.
2. Select the **Production** environment.
3. Copy the **API key**.
Examples:
Configure the SDK in your `Application` class:
```kotlin theme={null}
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"
)
}
}
```
Initialize the SDK with your **API key**. Must be called in `Application.onCreate()` before any other SDK methods.
Parameters:
* `context` Application context.
* `apiKey` (String, required): Your Appstack API key.
* `isDebug` (Bool, default: false): Leave as ‘false’ for production. See [**Development setup**](#development-setup) if you need to test against the development environment.
* `logLevel` (LogLevel, default: Loglevel.INFO): Logging level for debugging.
Example:
```kotlin theme={null}
AppstackAttributionSdk.configure(
context = this,
apiKey = "your-api-key",
isDebug = BuildConfig.DEBUG,
logLevel = LogLevel.INFO
)
```
Track user actions and revenue in your activities:
```kotlin theme={null}
// 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 values**
It 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_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.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:
1. `revenue` or `price` (number).
2. `currency` (string, e.g. `EUR`, `USD`).
```kotlin theme={null}
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:
1. `email`.
2. `name` (first + last name in the same field).
3. `phone_number`.
4. `date_of_birth` (recommended format: `YYYY-MM-DD`).
## **Limitations**
### **Platform constraints**
* Android 5.0+ required (API level 21).
* Attribution only works for Play Store installations.
* Network connectivity required for event transmission (with offline queueing).
### **Event tracking**
* The SDK must be initialized in `Application.onCreate()` before tracking calls.
* Custom event names should be descriptive and consistent.
* The debug overlay is only available when `isDebug = true`.
## Development setup
If you want to test the SDK against the Appstack development environment before shipping, follow these extra steps:
1. 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.
2. In your `configure(...)` call, use the development key and set `isDebug = true`:
```kotlin theme={null}
AppstackAttributionSdk.configure(
context = this,
apiKey = "your_development_api_key",
isDebug = true,
logLevel = LogLevel.DEBUG
)
```
The `isDebug` flag must match the key you're using: development key with `isDebug = true`, production key with `isDebug = false`. The flag tells the SDK which environment URL to route to.
**Debug mode**
Shows debug overlay with SDK status and event information. Only works when `isDebug = true`.
Example:
```kotlin theme={null}
if (BuildConfig.DEBUG) {
AppstackAttributionSdk.showDebugOverlay(this)
}
```
## **Superwall**
To start using the Superwall integration, [click here](/Integrations/superwall) to see the correct SDK documentation.
## **Support**
For questions or issues:
1. Check the [GitHub Repository](https://github.com/appstack-tech/appstack-android-sdk).
2. Contact our support team at [support@appstack.tech](mailto:support@appstack.tech)
3. Open an issue in the repository.
You are an expert Android engineer reviewing my existing Appstack Android SDK (Kotlin) integration. You are running inside an IDE assistant such as Cursor or Claude Code and you can see my codebase.
Your goal is to **validate that my integration fully matches the official Kotlin SDK documentation** and identify any missing or incorrect steps. When I paste this prompt and share my project files, you should:
1. **Gradle & environment**
* Inspect my Gradle files (project and app module) to confirm:
* The Appstack SDK dependency is present with the correct Maven coordinates (`tech.appstack.android-sdk:appstack-android-sdk`) and a valid version.
* Minimum SDK is at least API 21, target SDK is 34+, Java is 8+, and Gradle is 7.0+.
* Required repositories (including Maven Central) are configured so the SDK can resolve.
* Call out any mismatches or improvements needed.
2. **SDK initialization**
* Locate my `Application` class and verify:
* It is registered in the `AndroidManifest.xml`.
* `AppstackAttributionSdk.configure(...)` is called in `Application.onCreate()` before any event tracking.
* The call passes a valid `context` and `apiKey`, and uses optional parameters (`isDebug`, `logLevel`, `endpointBaseUrl`) appropriately when present.
* Suggest exact code changes if initialization is missing, in the wrong place, or misconfigured.
3. **Debug configuration**
* Check whether I conditionally enable debug features only for debug builds, for example:
* `isDebug = BuildConfig.DEBUG` in `configure(...)`.
* `AppstackAttributionSdk.showDebugOverlay(this)` wrapped in a `BuildConfig.DEBUG` guard when used.
* Warn if any debug-only behavior is accidentally enabled for release builds and propose safe patterns.
4. **Event tracking implementation**
* Find all uses of `AppstackAttributionSdk.sendEvent(...)` and verify:
* Standard `EventType` values are used where appropriate (e.g. `SIGN_UP`, `LOGIN`, `PURCHASE`, `SUBSCRIBE`, `ADD_TO_WISHLIST`, `INITIATE_CHECKOUT`, `START_TRIAL`, `LEVEL_START`, `LEVEL_COMPLETE`, `TUTORIAL_COMPLETE`, `SEARCH`, `SHARE`).
* Revenue-related events (such as `PURCHASE`) send `revenue` or `price` and `currency` parameters.
* Custom events use `EventType.CUSTOM` with a meaningful `name` and, when possible, parameters such as `email`, `name`, `phone_number`, and `date_of_birth` to support enhanced app campaigns.
* Highlight any missing or inconsistent events and propose concrete event calls that fit my app’s structure and flows.
5. **Limitations & platform assumptions**
* Confirm that my integration respects the documented limitations:
* App supports Android 5.0+ (API 21+).
* I understand attribution works for Play Store installs and that network connectivity is required (with offline queueing).
* Flag any edge cases in my setup that might conflict with these assumptions.
6. **Validation report & checklist**
* Produce a clear report summarizing:
* What is already correctly implemented and safe to ship.
* What is missing, misconfigured, or risky, with specific file names, functions, and code snippets to change.
* End with a **checklist of verification steps** (Gradle, Application init, debug overlay, key event tracking patterns) that I can tick off to confirm the integration fully matches the Kotlin SDK documentation.