​

Core Concepts

​

SDK Architecture

// Access module namespaces
AppDNA.pushModule.requestPermission()
AppDNA.billing.getProducts(["premium_monthly"])
AppDNA.experiments.getVariant("onboarding-v2")
AppDNA.remoteConfig.get("welcome_message")

// Access module namespaces
AppDNA.push.requestPermission(activity)
AppDNA.billing.getProducts(listOf("premium_monthly"))
AppDNA.experiments.getVariant("onboarding-v2")
AppDNA.remoteConfig.get("welcome_message")

// Access module namespaces
await AppDNA.push.requestPermission();
await AppDNA.billing.getProducts(["premium_monthly"]);
await AppDNA.experiments.getVariant("onboarding-v2");
await AppDNA.remoteConfig.get("welcome_message");

// Access module namespaces
await AppDNA.push.requestPermission();
await AppDNA.billing.getProducts(["premium_monthly"]);
await AppDNA.experiments.getVariant("onboarding-v2");
await AppDNA.remoteConfig.get("welcome_message");

​

Offline-First Design

​

Configuration Priority

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

​

Event Queue

1. The event is written to a persistent on-disk queue (a JSON file in Application Support on iOS, a SQLite database on Android).
2. The queue is auto-flushed every 30 seconds, when the app goes to the background or returns to the foreground, and when it 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), capped by the batchSize option when you set one. Each upload sends at most that many events.
3. If the flush fails (no connectivity, a 5xx, a 408 or a 429), events remain in the queue and are retried.
4. Events are removed from the queue after a successful upload.

​

Config Bundle

​

How It Works

1. The server regenerates the bundle after every publish that changes SDK config (publishes are grouped into fixed 15-second clock windows — :00–:15, :15–:30 and so on, not 15 seconds from the first publish — and each window’s publishes are built together, once, about a second after the window ends, so a new bundle is usually ready within about 20 seconds of a publish), from the same documents the SDK reads live. Regenerate under Settings → SDK → Config Bundle in the Console, or POST /api/v1/sdk/config-bundle/generate, builds one at once.
2. Your build downloads it with your SDK key (GET /api/v1/sdk/config-bundle) and embeds it in the app binary as appdna-config.json. See Config Bundles in CI/CD.
3. The SDK never downloads bundles. It reads the embedded file once its bootstrap request has succeeded or failed, and uses it for the sections it has no cached config for, typically on a first launch without network. A remote fetch from Firestore replaces it.

​

Embedding a Bundle

​

Experiments

​

How Bucketing Works

​

Key Properties

• Deterministic: The same user ID always gets the same variant for the same experiment. No randomness, no server dependency.
• Cross-platform consistent: A user identified with the same user ID on iOS and Android sees the same variant because the hash function and inputs are identical. Before identify(), each device buckets by its own anonymous ID.
• Session-stable: The variant does not change between sessions or app restarts while the user ID stays the same.
• Exposure tracking: The SDK records an exposure event the first time it assigns a variant for an experiment, and again only after the app restarts or reset() is called. Results count each anonymous ID once per experiment.

​

Servable Surface Experiments

let variant = AppDNA.experiments.getVariant("onboarding-v2")

switch variant {
case "control":
    showClassicOnboarding()
case "streamlined":
    showStreamlinedOnboarding()
default:
    showClassicOnboarding()
}

val variant = AppDNA.experiments.getVariant("onboarding-v2")

when (variant) {
    "control" -> showClassicOnboarding()
    "streamlined" -> showStreamlinedOnboarding()
    else -> showClassicOnboarding()
}

final variant = await AppDNA.experiments.getVariant("onboarding-v2");

if (variant == "streamlined") {
  showStreamlinedOnboarding();
} else {
  showClassicOnboarding();
}

const variant = await AppDNA.experiments.getVariant("onboarding-v2");

if (variant === "streamlined") {
  showStreamlinedOnboarding();
} else {
  showClassicOnboarding();
}

​

Delegates and Callbacks

class MyPaywallHandler: AppDNAPaywallDelegate {
    func onPaywallPresented(paywallId: String) {
        // Track in your own analytics
    }

    func onPaywallDismissed(paywallId: String) {
        // Handle purchase or dismissal
    }
}

AppDNA.paywall.setDelegate(MyPaywallHandler())

AppDNA.paywall.setDelegate(object : AppDNAPaywallDelegate {
    override fun onPaywallPresented(paywallId: String) {
        // Track in your own analytics
    }

    override fun onPaywallDismissed(paywallId: String) {
        // Handle purchase or dismissal
    }
})

class MyPaywallHandler extends AppDNAPaywallDelegate {
  @override
  void onPaywallPresented(String paywallId) {
    // Track in your own analytics
  }

  @override
  void onPaywallDismissed(String paywallId) {
    // Handle purchase or dismissal
  }
}

AppDNA.paywall.setDelegate(MyPaywallHandler());

const paywallDelegate: AppDNAPaywallDelegate = {
  onPaywallPresented: (paywallId) => {
    // Track in your own analytics
  },
  onPaywallDismissed: (paywallId) => {
    // Handle purchase or dismissal
  },
  // ...implement the other AppDNAPaywallDelegate methods (purchase, restore, promo)
};

AppDNA.paywall.setDelegate(paywallDelegate);

// Detach when you no longer need callbacks:
AppDNA.paywall.setDelegate(null);

​

Environments

• Events, experiments, and configuration are completely isolated between environments.
• Use sandbox during development and testing. Switch to production for App Store / Play Store builds.
• The SDK determines the environment from the API key prefix — there is no need to set it separately if the key is correct.

​

Webhooks

​

Event Types

​

Security

X-AppDNA-Signature: sha256=<hex-encoded HMAC of request body>

​

Reliability

• 5 attempts total (1 initial delivery + 4 retries) with backoff at 30s, 2min, 10min, 1hr.
• Your endpoint must respond with a 2xx status within 30 seconds or the attempt is considered failed.
• After 50 consecutive failures, the webhook endpoint is automatically disabled (disabled_reason: consecutive_failures). Re-enable it from the dashboard or via the API after fixing the issue.
• You can view delivery logs and manually retry failed deliveries in the dashboard.

​

Identity

​

Anonymous ID

​

Linking Identity

Anonymous ID (auto-generated)  ──identify()──▶  User ID (your system)

​

Resetting Identity

// User signs out
AppDNA.reset()

// New user signs in
AppDNA.identify(userId: "user-456", traits: ["plan": "free"])

// User signs out
AppDNA.reset()

// New user signs in
AppDNA.identify(userId = "user-456", traits = mapOf("plan" to "free"))

// User signs out
await AppDNA.reset();

// New user signs in
await AppDNA.identify("user-456", traits: {"plan": "free"});

// User signs out
await AppDNA.reset();

// New user signs in
await AppDNA.identify("user-456", { plan: "free" });