Android Quickstart

Supported on: Android SDK 1.0.33+

This guide walks you through configuring the AppDNA SDK, identifying users, and tracking your first event.

1. Configure the SDK

Initialize AppDNA as early as possible in your app lifecycle. Place the configuration call in your Application.onCreate() method:

import ai.appdna.sdk.AppDNA
import ai.appdna.sdk.AppDNAOptions
import ai.appdna.sdk.Environment
import ai.appdna.sdk.LogLevel
import android.app.Application

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

        AppDNA.configure(
            context = this,
            apiKey = "adn_live_xxx",
            environment = Environment.PRODUCTION,
            options = AppDNAOptions(logLevel = LogLevel.DEBUG)
        )
    }
}

Firebase is automatically initialized from google-services-appdna.json on Android. You do not need to call any Firebase initialization method manually. Ensure that google-services-appdna.json is in your app/ directory and the Google Services plugin is applied (see Installation).

If your app already uses Firebase for your own services (Analytics, Crashlytics, Realtime Database), AppDNA automatically creates a separate named Firebase instance. Your existing Firebase setup is not affected.

Call AppDNA.configure(...) exactly once before using any other SDK methods. Calling it multiple times will result in undefined behavior. Always call it in Application.onCreate(), not in an Activity.

Configuration Options

The AppDNAOptions data class lets you customize SDK behavior:

Parameter	Type	Default	Description
`flushInterval`	`Long`	`30L` (seconds)	Seconds between automatic event flushes. When not set (left at `30L`), the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`batchSize`	`Int`	`100` (not set)	A cap on the batch size the network sets (100 on Wi-Fi or wired; on cellular, 20 when the system marks the connection expensive (iOS: every cellular connection) or metered (Android: most plans), otherwise 50): the queue is flushed when it reaches the smaller of the two, and each upload sends at most that many. When not set, the value the server returns with the SDK’s bootstrap request is the cap if it is positive (100 today, so nothing is capped). A value below 1 is ignored (the SDK logs a warning), as if not set. Passing the default (100) is the same as not setting it. If your app already passed `batchSize` to an earlier SDK version — where it had no effect — it is now a hard cap: each upload sends at most that many events. Remove it, or raise it, unless that is what you want.
`configTTL`	`Long`	`3600L` (seconds)	Seconds before cached config is considered stale. When not set (left at `3600L`), the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`logLevel`	`LogLevel`	`LogLevel.WARNING`	Verbosity of SDK console logs
`billingProvider`	`BillingProvider`	`BillingProvider.StoreKit2`	Who owns purchases. Omitted = `StoreKit2` (AppDNA’s own billing against Google Play); `RevenueCat` / `Adapty` when that SDK makes your purchases (AppDNA then never acknowledges, and SDK paywall taps report `providerNotAvailable`); `None` disables billing. See Billing
`vetoTimeout`	`Long`	`5L` (seconds)	Used by the Flutter and React Native bridges to bound host hooks. Unused by a native Android host: its `onBeforeStepAdvance` is not timed out, `onBeforeStepRender` ends at 3 s and a `refresh` interaction at 8 s

Environment

The Environment enum controls which backend the SDK targets:

Value	Endpoint	Description
`Environment.PRODUCTION`	`https://api.appdna.ai`	Production API and configuration
`Environment.SANDBOX`	`https://api.appdna.ai`	Same endpoint as production — sandbox is routed via your `adn_test_*` API-key prefix. Use a test key from the Console to send traffic to the sandbox pipeline.

Log Level

The LogLevel enum controls Logcat log verbosity:

Value	Raw Value	Description
`LogLevel.NONE`	`0`	No logging
`LogLevel.ERROR`	`1`	Errors only
`LogLevel.WARNING`	`2`	Errors and warnings
`LogLevel.INFO`	`3`	Errors, warnings, and info
`LogLevel.DEBUG`	`4`	All messages including debug

Use LogLevel.DEBUG during development to see all SDK activity in Logcat. Switch to LogLevel.WARNING or LogLevel.NONE for production builds.

2. Wait for Ready State

Use onReady to know when the SDK is ready — the bootstrap has succeeded or failed:

AppDNA.onReady {
    Log.d("AppDNA", "SDK ready")
}

onReady does not wait for the remote configuration. When it fires, the SDK serves the cached and bundled config, and the remote fetch may still be running (after a failed bootstrap it starts when a retry succeeds). Use remoteConfig.onChanged to pick up the fetched values.

3. Identify Users

Once a user signs in, call identify to associate events with their user ID:

AppDNA.identify(
    userId = "user-123",
    traits = mapOf(
        "plan" to "premium",
        "signup_date" to "2025-01-15"
    )
)

Traits are merged with any previously set traits. You do not need to pass all traits on every call — only the ones that have changed.

4. Track Events

Track user actions with track:

AppDNA.track(
    event = "workout_completed",
    properties = mapOf(
        "duration" to 45,
        "type" to "strength"
    )
)

Events are batched and flushed automatically: every flushInterval seconds, when the app goes to the background or returns to the foreground, and when the queue reaches a batch size set by the network (100 events on Wi-Fi or a wired connection, metered or not; 20 on a cellular connection the system marks as expensive (iOS) or metered (Android), which is every cellular connection on iOS and most cellular plans on Android; 50 on any other cellular connection). The batchSize option caps it: with a cap, the queue is flushed at the smaller of the two, and no upload sends more.

5. Flush Events Manually

Force an immediate flush of all queued events:

AppDNA.flush()

This is useful before the app enters the background or when you need to ensure events are sent immediately. Control whether the SDK collects and sends analytics data:

AppDNA.setConsent(analytics = true)

When analytics is set to false, events are silently dropped and not queued. No data is sent to AppDNA servers until consent is granted.

7. Change Log Level at Runtime

You can adjust the log level after configuration without restarting the app:

AppDNA.setLogLevel("debug")

Accepted values: "none", "error", "warning", "info", "debug".

8. Remote Config and Feature Flags

Retrieve server-side configuration values:

val welcomeMessage = AppDNA.getRemoteConfig("welcome_message")

Check whether a feature flag is enabled:

val darkModeEnabled = AppDNA.isFeatureEnabled("dark_mode")

9. Experiments

Get the variant assigned to a user for an experiment:

val variant = AppDNA.getExperimentVariant("paywall_test")

Check if the user is in a specific variant:

val isInVariantB = AppDNA.isInVariant("paywall_test", "b")

10. Session Data

Store cross-module session data that can be used in template interpolation across onboarding flows, paywalls, and in-app messages:

// Store session data
AppDNA.setSessionData(key = "selected_plan", value = "premium")
AppDNA.setSessionData(key = "referral_code", value = "FRIEND2026")

// Retrieve session data
val plan = AppDNA.getSessionData(key = "selected_plan") // "premium"

// Clear the values set with setSessionData (reset() clears onboarding answers too)
AppDNA.clearSessionData()

Session data values are accessible in Console-configured content using template syntax: {{session.selected_plan}}.

11. Reset on Logout

When a user signs out, call reset to clear identity-scoped state:

AppDNA.reset()

This clears the identified user, resets experiment exposures, clears in-session message/survey state, and stops the web-entitlement observer. The anonymous device identifier persists across reset() calls. Call AppDNA.flush() separately if you also want to drain the event queue before logout.

You now have the SDK configured, user identification, event tracking, remote config, experiments, and session data working. Continue to the module-specific guides for Push Notifications, Billing, Onboarding, and Paywalls.

​1. Configure the SDK

​Configuration Options

​Environment

​Log Level

​2. Wait for Ready State

​3. Identify Users

​4. Track Events

​5. Flush Events Manually

​6. Set User Consent

​7. Change Log Level at Runtime

​8. Remote Config and Feature Flags

​9. Experiments

​10. Session Data

​11. Reset on Logout

1. Configure the SDK

Configuration Options

Environment

Log Level

2. Wait for Ready State

3. Identify Users

4. Track Events

5. Flush Events Manually

6. Set User Consent

7. Change Log Level at Runtime

8. Remote Config and Feature Flags

9. Experiments

10. Session Data

11. Reset on Logout