SDK Overview - AppDNA

AppDNA provides native SDKs for every major mobile platform. All four SDKs share an identical API surface, the same offline-first architecture, and full feature parity. Choose the SDK that matches your stack and get started in minutes.

Choose Your Platform

iOS

Native Swift SDK distributed via Swift Package Manager and CocoaPods. Requires iOS 16.0+ and Swift 5.9+.

Android

Kotlin SDK distributed via Maven Central (Gradle). Requires Android API 24+ and Kotlin 1.9+.

Flutter

Dart package distributed via pub.dev. Requires Flutter 3.10+ and Dart 3.0+.

React Native

TypeScript package distributed via npm. Requires React Native 0.76.9+ with the New Architecture enabled (RN 0.77+/Kotlin 2.0 supported via a version-gated Compose config).

Platform Comparison

Requirements

	iOS	Android	Flutter	React Native
Package	`AppDNASDK`	`ai.appdna.sdk`	`appdna_sdk`	`@appdna-ai/react-native-sdk`
Language	Swift 5.9+	Kotlin 1.9+	Dart 3.0+	TypeScript
Min Platform	iOS 16.0	Android API 24	Flutter 3.10+	React Native 0.76.9+ (New Arch)
Distribution	SPM, CocoaPods	Maven Central (Gradle)	pub.dev	npm
Current Version	1.0.83	1.0.55	1.0.21	1.0.20

The React Native SDK requires the New Architecture. All four SDKs are generally available.

iOS 1.0.77 adds a case to the public AppDNAInitError enum. If you switch over it exhaustively your build needs one extra case — see iOS Installation. No other API changed, and nothing changes at runtime.

Dependencies

	iOS	Android	Flutter	React Native
HTTP	URLSession (built-in)	OkHttp3	Platform channels	NativeModules bridge
Billing	StoreKit 2 (built-in)	Google Play Billing 7.0	Platform channels to native	NativeModules bridge
Config Sync	FirebaseFirestore	Firebase Firestore 25.1.1	Platform channels to native	NativeEventEmitter
Secure Storage	KeychainAccess	EncryptedSharedPreferences	Platform-specific	Platform-specific

Flutter and React Native SDKs bridge to the native iOS and Android implementations under the hood. You do not need to add native dependencies manually — they are bundled with the SDK.

Core API

Every SDK exposes the same five core methods. The API is intentionally minimal — initialize once, identify your user, track events, and the SDK handles the rest.

`configure`

Initialize the SDK with your API key. Call this exactly once at app startup.

iOS
Android
Flutter
React Native

import AppDNASDK

AppDNA.configure(
    apiKey: "adn_live_xxx",
    environment: .production,
    options: AppDNAOptions(logLevel: .debug)
)

import ai.appdna.sdk.AppDNA
import ai.appdna.sdk.AppDNAOptions
import ai.appdna.sdk.Environment

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

import 'package:appdna_sdk/appdna_sdk.dart';

await AppDNA.configure(
  apiKey: "adn_live_xxx",
  env: AppDNAEnvironment.production,
  options: AppDNAOptions(logLevel: AppDNALogLevel.debug),
);

import { AppDNA } from '@appdna-ai/react-native-sdk';

await AppDNA.configure("adn_live_xxx", "production", {
  logLevel: "debug",
});

`identify`

Link a user identity with optional traits. Traits are merged with previously set values.

iOS
Android
Flutter
React Native

AppDNA.identify(
    userId: "user-123",
    traits: ["plan": "premium", "signup_date": "2025-01-15"]
)

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

await AppDNA.identify("user-123", traits: {
  "plan": "premium",
  "signup_date": "2025-01-15",
});

await AppDNA.identify("user-123", {
  plan: "premium",
  signup_date: "2025-01-15",
});

`track`

Record a custom event with optional properties. Events are queued locally and flushed automatically.

iOS
Android
Flutter
React Native

AppDNA.track(
    event: "workout_completed",
    properties: ["duration": 45, "type": "strength"]
)

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

await AppDNA.track("workout_completed", properties: {
  "duration": 45,
  "type": "strength",
});

await AppDNA.track("workout_completed", {
  duration: 45,
  type: "strength",
});

`reset`

Clear the user identity on sign-out. The anonymous ID is preserved so device-level analytics continue uninterrupted.

iOS
Android
Flutter
React Native

AppDNA.reset()

AppDNA.reset()

await AppDNA.reset();

await AppDNA.reset();

`flush`

Force-send all queued events immediately. Useful before the app enters the background.

iOS
Android
Flutter
React Native

AppDNA.flush()

AppDNA.flush()

await AppDNA.flush();

await AppDNA.flush();

Module Namespaces

Beyond the core API, the SDK organizes features into 10 module namespaces. Each namespace is accessed as a property on the AppDNA singleton and operates independently while sharing the core event pipeline, identity state, and configuration layer.

Namespace	Purpose	Example
`push`	Push notification registration and handling	`AppDNA.push.requestPermission()` (on iOS the namespace is `pushModule`)
`billing`	Subscription status, product fetching, purchases	`AppDNA.billing.getProducts(["premium_monthly"])`
`onboarding`	Server-driven onboarding flow presentation	`AppDNA.onboarding.present("welcome")`
`paywall`	Server-driven paywall rendering and events	`AppDNA.paywall.present("premium")`
`remoteConfig`	Key-value remote configuration	`AppDNA.remoteConfig.get("key")`
`features`	Feature flags and entitlements	`AppDNA.features.isEnabled("dark_mode")`
`experiments`	A/B experiment assignment and exposure tracking	`AppDNA.experiments.getVariant("test")`
`surveys`	In-app survey presentation and response collection	`AppDNA.surveys.present("nps")`
`inAppMessages`	Triggered in-app messaging	`AppDNA.inAppMessages.suppressDisplay(false)`
`deepLinks`	Deep link routing and deferred deep links	`AppDNA.deepLinks.handleURL(url)`

Every namespace is available on all four SDKs. Flutter and React Native are thin wrappers over the same native iOS and Android renderers, so the module surface is the same one — not a re-implementation of it.

Delegate and Callback Protocols

Each module that communicates events back to your application uses a delegate or callback pattern. The core delegate protocols shared across all platforms include:

Protocol	Key Methods	Used By
`AppDNAOnboardingDelegate`	Flow started, step changed, flow completed, flow dismissed	`onboarding`
`AppDNAPaywallDelegate`	Presented, dismissed, purchase started/completed/failed, promo code	`paywall`
`AppDNASurveyDelegate`	Presented, completed (with responses), dismissed	`surveys`
`AppDNAInAppMessageDelegate`	Shown, action taken, dismissed, shouldShowMessage gate	`inAppMessages`
`AppDNADeepLinkDelegate`	Deep link received (url + params)	`deepLinks`
`AppDNAPushDelegate`	Token received, notification presented, notification opened	`pushModule`

iOS
Android
Flutter
React Native

Implement Swift protocols with default empty methods. Conform to only what you need:

class MyHandler: AppDNAPaywallDelegate {
    func onPaywallPresented(paywallId: String) { }
    func onPaywallDismissed(paywallId: String) { }
}

AppDNA.paywall.setDelegate(MyHandler())

Implement Kotlin interfaces with default methods. Override only what you need:

AppDNA.paywall.setDelegate(object : AppDNAPaywallDelegate {
    override fun onPaywallPresented(paywallId: String) { }
    override fun onPaywallDismissed(paywallId: String) { }
})

Extend Dart abstract classes:

class MyHandler extends AppDNAPaywallDelegate {
  @override
  void onPaywallPresented(String paywallId) { }
  @override
  void onPaywallDismissed(String paywallId) { }
}

AppDNA.paywall.setDelegate(MyHandler());

Implement the delegate interface and register it once:

const delegate: AppDNAPaywallDelegate = {
  onPaywallPresented: (paywallId) => {},
  onPaywallDismissed: (paywallId) => {},
  onPaywallAction: (paywallId, action) => {},
  onPaywallPurchaseStarted: () => {},
  onPaywallPurchaseCompleted: () => {},
  onPaywallPurchaseFailed: () => {},
  onPaywallRestoreStarted: () => {},
  onPaywallRestoreCompleted: () => {},
  onPaywallRestoreFailed: () => {},
  onPostPurchaseDeepLink: () => {},
  onPostPurchaseNextStep: () => {},
};

AppDNA.paywall.setDelegate(delegate);

Architecture

Offline-First Design

All four SDKs share the same offline-first architecture. Your app never crashes or degrades because of a network issue. Configuration priority — the SDK resolves config using a three-tier fallback:

Remote (fetched from Firestore at configure, on TTL expiry and on refresh)
    |
    v  unavailable?
Cached (last successful fetch, persisted on device)
    |
    v  unavailable?
Bundled (appdna-config.json embedded in the app binary)

Event queue — events are persisted to disk, batched, and flushed automatically:

Setting	Default	Description
Flush interval	30 seconds	Time between automatic flushes
Batch size	100 / 50 / 20 events	Set by the network (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) and capped by the `batchSize` option when set; the queue is flushed when it reaches this size and each upload sends at most this many
Config TTL	1 hour	Time before cached config is considered stale

Events survive app restarts and device reboots. They are removed from the queue after a successful upload, or dropped when the server rejects the batch with a 4xx other than 408 / 429, when they are older than 7 days, when the queue passes 10,000 events or 5 MB, or when analytics consent is revoked. See Offline-First Architecture.

Experiment Bucketing

All SDKs assign variants on the device with the same MurmurHash3 (32-bit) hash:

bucket = murmur3_32("<experimentId>.<salt>.<userId>") % 10000

userId is the identified user ID, or the anonymous ID before identify(). The same ID gets the same variant for the same experiment on every platform and in every session, with no server round-trip, as long as the user passes the experiment’s targeting rules and traffic allocation. See Experiments.

Config Bundle for CI/CD

The server regenerates the config bundle shortly after each publish (usually within about 20 seconds; Regenerate under Settings → SDK → Config Bundle builds one at once). Download it at build time as in Config Bundles in CI/CD, and embed it in your app binary so that a first launch without network has config. The native SDK reads the file:

iOS
Android
Flutter
React Native

Add appdna-config.json to your Xcode project as a bundle resource.

Place appdna-config.json at app/src/main/assets/appdna-config.json.

Add ios/Runner/appdna-config.json to the Runner target (Copy Bundle Resources) and place the file at android/app/src/main/assets/appdna-config.json. A file declared under flutter: assets: in pubspec.yaml is not found by the SDK.

Add appdna-config.json to your Xcode project as a bundle resource (Copy Bundle Resources) and place it at android/app/src/main/assets/appdna-config.json. A file in the project root or your JS sources is not found by the SDK.

Feature Parity Matrix

All four SDKs have feature parity. Flutter and React Native wrap the native iOS and Android SDKs — the rendering, business logic, storage, and network I/O are the same code paths, reached through a thin facade.

Feature	iOS	Android	Flutter	React Native
Event tracking	Yes	Yes	Yes	Yes
User identification	Yes	Yes	Yes	Yes
Offline event queue	Yes	Yes	Yes	Yes
Remote config	Yes	Yes	Yes	Yes
Feature flags	Yes	Yes	Yes	Yes
A/B experiments	Yes	Yes	Yes	Yes
Push notifications	Yes	Yes	Yes	Yes
Billing / subscriptions	Yes	Yes	Yes	Yes
Server-driven onboarding	Yes	Yes	Yes	Yes
Server-driven paywalls	Yes	Yes	Yes	Yes
In-app messages	Yes	Yes	Yes	Yes
Surveys	Yes	Yes	Yes	Yes
Deep links	Yes	Yes	Yes	Yes
Config bundle embedding	Yes	Yes	Yes	Yes
Consent management	Yes	Yes	Yes	Yes
Deterministic experiments	Yes	Yes	Yes	Yes

Configuration Options

All SDKs accept the same configuration options at initialization:

Option	Type	Default	Description
`flushInterval`	number	`30`	Seconds between automatic event flushes. When not set, the value the server returns with the SDK’s bootstrap request applies once the bootstrap succeeds, if it is positive
`batchSize`	number	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 server’s value from the 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`	number	`3600`	Seconds before cached config is stale. When not set, the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`logLevel`	enum	`warning`	Console log verbosity: `none`, `error`, `warning`, `info`, `debug`
`billingProvider`	enum	`storeKit2`	Who owns store transactions. `storeKit2` (also when omitted) = AppDNA’s own billing on both platforms (StoreKit 2 on iOS, Google Play Billing on Android): the SDK buys, finishes / acknowledges and reports purchases. `revenueCat` / `adapty` = that provider owns purchases: the SDK never finishes or acknowledges a transaction, an SDK paywall tap calls `onPaywallPurchaseFailed` with `errorType: providerNotAvailable` (always on Android and always under `adapty`; under `revenueCat` on iOS in every published CocoaPods / SPM build: the iOS SDK buys through RevenueCat only when RevenueCat is linked into AppDNA itself, in a source or vendored build — linking it into your app is not enough; it never buys through Adapty, linked or not), and purchases reach AppDNA through the provider’s webhook. `none` disables billing. See each platform’s Billing page.
`vetoTimeout`	number	`5`	Seconds the Flutter and React Native bridges wait for a synchronous host hook (for example `onBeforeStepAdvance`) before continuing without an answer. React Native takes fractional seconds on both platforms (`0.5` waits 500 ms); Flutter’s `vetoTimeout` is an `int`. It bounds every host hook on those bridges; sign-in actions always wait at least 120 s, and a sign-in action that times out blocks: the user stays on the step and sees an error. A non-positive value falls back to the default. Natively (iOS / Android), `onBeforeStepAdvance` has no timeout, `onBeforeStepRender` ends at 3 s and a `refresh` interaction at 8 s; those two native deadlines also apply under the Flutter and React Native bridges. A shorter `vetoTimeout` ends an `onBeforeStepRender` wait sooner. A `refresh` gets 8 s whatever `vetoTimeout` is: the bridges wait `max(vetoTimeout, 8 s)` for it, so a shorter `vetoTimeout` does not cut it short, and the SDK ends it at 8 s, so a larger one does not extend it.

iOS only: the Info.plist keys AppDNADisableNotificationProxy (Boolean — turns off the launch-time notification delegate proxy) and AppDNAForegroundPresentation (array of banner, list, sound, badge — how AppDNA pushes are presented in the foreground) are read from your app’s Info.plist, not passed as runtime options. See the iOS Push page.

Use logLevel: debug during development and logLevel: warning or logLevel: none for production builds.

Environments

Environment	API Base URL	Key Prefix
Production	`https://api.appdna.ai`	`adn_live_`
Sandbox	`https://api.appdna.ai`	`adn_test_`

Events, experiments, and configuration are completely isolated between environments. The SDK auto-detects the environment from your API key prefix.

Two key families exist and the server accepts both: adn_live_ / adn_test_ (Settings → SDK → API Keys) and pk_live_ / pk_sandbox_ (issued by the app-setup wizard and listed under Settings → SDK Keys, /settings/sdk-keys). Use an adn_ key for the SDK. A pk_ key works, but the native iOS and Android SDKs log “API key format invalid” at configure, and on iOS diagnose() also reports “invalid format” for it (Android’s diagnose() does not check the key format).

Never ship an app to production with a sandbox API key. Sandbox data is periodically purged and is not included in production analytics.

Next Steps

iOS Installation

Add AppDNA to your Xcode project via SPM or CocoaPods.

Android Installation

Add AppDNA to your Gradle build.

Flutter Installation

Add the appdna_sdk package from pub.dev.

React Native Installation

Install @appdna-ai/react-native-sdk from npm.

For architecture deep dives, see the Core Concepts page. For CI/CD integration with config bundles, see the Config Bundle Guide.

​Choose Your Platform

iOS

Android

Flutter

React Native

​Platform Comparison

​Requirements

​Dependencies

​Core API

​configure

​identify

​track

​reset

​flush

​Module Namespaces

​Delegate and Callback Protocols

​Architecture

​Offline-First Design

​Experiment Bucketing

​Config Bundle for CI/CD

​Feature Parity Matrix

​Configuration Options

​Environments

​Next Steps

iOS Installation

Android Installation

Flutter Installation

React Native Installation

Choose Your Platform

Platform Comparison

Requirements

Dependencies

Core API

`configure`

`identify`

`track`

`reset`

`flush`

Module Namespaces

Delegate and Callback Protocols

Architecture

Offline-First Design

Experiment Bucketing

Config Bundle for CI/CD

Feature Parity Matrix

Configuration Options

Environments

Next Steps