> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appdna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Android Installation

> Add AppDNA to your Android project

<Info>
  **Supported on:** Android SDK `1.0.33+`
</Info>

## Requirements

Before integrating the AppDNA Android SDK, ensure your project meets the following minimum requirements:

| Requirement | Minimum Version |
| ----------- | --------------- |
| minSdk      | 24              |
| targetSdk   | 35              |
| compileSdk  | 35              |
| Kotlin      | 1.9.22+         |
| Java        | 17              |

<Warning>
  Projects targeting API levels below 24 (Android 7.0) are not supported. The SDK uses Kotlin coroutines and modern Android APIs that require minSdk 24 as a baseline.
</Warning>

## Installation

### Gradle (Kotlin DSL)

Add the AppDNA SDK to your module-level `build.gradle.kts`:

```kotlin theme={null}
dependencies {
    implementation("ai.appdna:sdk-android:1.0.43")
}
```

### Gradle (Groovy DSL)

If your project uses Groovy-based Gradle files, add the following to your `build.gradle`:

```groovy theme={null}
dependencies {
    implementation 'ai.appdna:sdk-android:1.0.43'
}
```

Then sync your project with Gradle files.

## Firebase Configuration

The AppDNA SDK uses Firebase Firestore for real-time configuration delivery (paywalls, experiments, feature flags, onboarding flows) and Firebase Cloud Messaging for push notifications. You must add a Firebase configuration file to your project.

### Step 1: Download google-services-appdna.json

1. Log into your [AppDNA Console](https://console.appdna.ai)
2. Go to **Settings → SDK**
3. Click **Download Firebase Config** to download `google-services-appdna.json`

### Step 2: Add to Your Project

Place the `google-services-appdna.json` file in your app module's `src/main/assets/` directory (the SDK loads it from the app's assets at runtime):

```
your-project/
  app/
    build.gradle.kts
    src/
      main/
        assets/
          google-services-appdna.json    <-- place here
```

### Step 3: Apply the Google Services Plugin

Add the Google Services classpath to your **project-level** `build.gradle` (or `build.gradle.kts`):

```groovy theme={null}
// build.gradle (project-level)
buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.0'
    }
}
```

Then apply the plugin in your **app-level** `build.gradle` (or `build.gradle.kts`):

```groovy theme={null}
// app/build.gradle
apply plugin: 'com.google.gms.google-services'
```

Or with Kotlin DSL:

```kotlin theme={null}
// app/build.gradle.kts
plugins {
    id("com.google.gms.google-services")
}
```

<Warning>
  Without `google-services-appdna.json`, the SDK cannot fetch remote configuration (paywalls, experiments, feature flags) or receive push notifications. Events will still be tracked, but remote features will not work.
</Warning>

<Note>
  If your app already uses Firebase for your own services (Analytics, Crashlytics, Realtime Database), AppDNA automatically creates a separate named Firebase instance using `google-services-appdna.json`. Your existing Firebase setup is not affected. Just add the AppDNA config file alongside your own `google-services.json`.
</Note>

## Dependencies

The following dependencies are automatically included with the SDK. You do not need to add them manually:

| Dependency          | Version | Purpose                                   |
| ------------------- | ------- | ----------------------------------------- |
| Firebase Firestore  | 25.1.1  | Real-time remote configuration sync       |
| Firebase Messaging  | 24.1.0  | Push notification delivery (FCM)          |
| OkHttp3             | 4.12.0  | HTTP networking                           |
| Google Play Billing | 7.0.0   | In-app purchase and subscription handling |
| Kotlin Coroutines   | 1.8.1   | Asynchronous operations                   |
| Lottie Compose      | 6.4.0   | Lottie animation rendering                |
| Rive Android        | 9.13.10 | Rive animation rendering                  |
| WorkManager         | 2.9.0   | Background event upload                   |

<Info>
  If your project already includes these dependencies, ensure your version constraints are compatible with the versions listed above. Gradle will resolve version conflicts automatically in most cases, but you may need to add resolution strategies for major version mismatches.
</Info>

### Optional Dependencies

| Dependency     | Version | Inclusion     | Purpose                     |
| -------------- | ------- | ------------- | --------------------------- |
| RevenueCat SDK | 8.4.0   | `compileOnly` | RevenueCat billing provider |

RevenueCat is declared as `compileOnly` and is only required if you configure RevenueCat as your billing provider. If you do not use RevenueCat, you do not need to add it.

### Jetpack Compose

The SDK uses Jetpack Compose for rendering paywalls and onboarding flows. Compose is enabled automatically using BOM `2024.02.02`. Ensure your project has Compose enabled in your module-level `build.gradle.kts`:

```kotlin theme={null}
android {
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8"
    }
}
```

## Verify Installation

After adding the SDK, verify it is correctly installed by importing the module and logging the SDK version:

```kotlin theme={null}
import ai.appdna.sdk.AppDNA
import android.util.Log

Log.d("AppDNA", AppDNA.sdkVersion) // "1.0.43"
```

<Check>
  You should see `1.0.43` printed in Logcat. If you get an unresolved reference error, clean your project (Build > Clean Project) and rebuild.
</Check>

## Troubleshooting

If you encounter issues during integration, call `AppDNA.diagnose()` after configuration to get a snapshot of SDK state. `diagnose()` **returns** a `String` — log it (or capture it for error reports) yourself:

```kotlin theme={null}
// Call a few seconds after configure() to allow bootstrap to complete
Handler(Looper.getMainLooper()).postDelayed({
    Log.d("AppDNA", AppDNA.diagnose())
}, 5_000)
```

The report is a plain-text snapshot:

```
=== AppDNA SDK diagnose ===
configured: true
environment: sandbox
base_url: https://api.appdna.ai
api_key: adn_test_…
sdk_version: 1.0.43
bundle_version: 12
anon_id: a1b2c3d4-e5f6-…
user_id: <unset>
org_id: org_…
app_id: app_…
consent.analytics: true
=== end ===
```

Any line that shows `<unset>` when it shouldn't, or `configured: false`, indicates a configuration issue. Common fixes:

| Symptom                                                   | Fix                                                                                                     |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `configured: false`                                       | Call `AppDNA.configure(...)` from `Application.onCreate()`                                              |
| `api_key: <unset>` or wrong prefix                        | Key must start with `adn_live_` or `adn_test_`                                                          |
| `org_id: <unset>` / `app_id: <unset>` after a few seconds | Bootstrap failed — check API key, network, and Firebase config                                          |
| `bundle_version: 0` for an extended period                | `google-services-appdna.json` missing from `app/src/main/assets/` or Google Services plugin not applied |

## Next Steps

Once the SDK is installed, proceed to the [Quickstart](/sdks/android/quickstart) guide to configure the SDK and start tracking events.