Android Installation

Supported on: Android SDK 1.0.33+

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

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.

Installation

Gradle (Kotlin DSL)

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

dependencies {
    implementation("ai.appdna:sdk-android:1.0.55")
}

Gradle (Groovy DSL)

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

dependencies {
    implementation 'ai.appdna:sdk-android:1.0.55'
}

Then sync your project with Gradle files.

Firebase Configuration

The AppDNA SDK uses Firebase Firestore for 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

Log into your AppDNA Console
Go to Settings → SDK
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):

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

// app/build.gradle
apply plugin: 'com.google.gms.google-services'

Or with Kotlin DSL:

// app/build.gradle.kts
plugins {
    id("com.google.gms.google-services")
}

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.

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.

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	Remote configuration fetch
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
Maps Compose	4.4.1	Pannable map blocks in onboarding

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.

Optional Dependencies

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

RevenueCat is declared as compileOnly; the SDK does not use it for purchases on Android. When RevenueCat is your purchase SDK, add it yourself, set billingProvider = BillingProvider.RevenueCat (the SDK then never verifies, acknowledges or consumes a purchase, and SDK paywall taps call onPaywallPurchaseFailed with errorType providerNotAvailable), and connect the RevenueCat webhook so purchases reach AppDNA. See Billing → Who owns a purchase.

Interactive maps (optional)

An onboarding step can contain a map. The SDK draws a static map with no setup at all — the provider key is delivered with your configuration, so there is nothing to add here.

Enable the Maps SDK for this platform in Google Cloud, alongside the Maps Static API the map image already uses: APIs & Services → Library → Maps SDK for Android. Pan & zoom is drawn by that SDK, so without it enabled the key is rejected at map start and the step falls back to the still image — every bit of wiring below can be correct and the map still will not move. See Maps for the full key setup.

A pannable, zoomable map is different, and only on Android. The Maps SDK for Android reads its key from the merged manifest at build time; there is no runtime setter, so a key we deliver cannot reach it. If your authors enable Pan & zoom on a Google map, add one line to your app’s AndroidManifest.xml:

<application>
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="YOUR_ANDROID_MAPS_API_KEY" />
</application>

Without it the SDK falls back to the static map rather than rendering the Maps SDK’s grey “no key” rectangle, so nothing breaks — the map simply does not pan. A key that is in the manifest but lacks “Maps SDK for Android” (or whose Android app restriction does not list your package and signing SHA-1) cannot be detected up front: the Maps SDK draws a grey map and reports “Authorization failure” only in logcat. When an interactive map has not finished loading 15 seconds after it appears, the SDK logs an error that names these causes (a slow network causes it too). It does not swap the map for the still image.

iOS needs none of this. The iOS Maps SDK takes its key at runtime, so a pannable map works there with no host changes. The key is always yours: Google bills map requests to the account that owns the key, so AppDNA never substitutes one of its own.

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:

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:

import ai.appdna.sdk.AppDNA
import android.util.Log

Log.d("AppDNA", AppDNA.sdkVersion) // "1.0.55"

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

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:

// 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.55
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`	No `appdna-config.json` in `app/src/main/assets/`, or one saved without `bundle_version`. Only matters if you want an offline first-launch fallback; download it as in Config Bundles in CI/CD

Next Steps

Once the SDK is installed, proceed to the Quickstart guide to configure the SDK and start tracking events.

​Requirements

​Installation

​Gradle (Kotlin DSL)

​Gradle (Groovy DSL)

​Firebase Configuration

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

​Step 2: Add to Your Project

​Step 3: Apply the Google Services Plugin

​Dependencies

​Optional Dependencies

​Interactive maps (optional)

​Jetpack Compose

​Verify Installation

​Troubleshooting

​Next Steps

Requirements

Installation

Gradle (Kotlin DSL)

Gradle (Groovy DSL)

Firebase Configuration

Step 1: Download google-services-appdna.json

Step 2: Add to Your Project

Step 3: Apply the Google Services Plugin

Dependencies

Optional Dependencies

Interactive maps (optional)

Jetpack Compose

Verify Installation

Troubleshooting

Next Steps