Android Offline Support

Supported on: Android SDK 1.0.33+

The AppDNA SDK is designed to work reliably in offline and low-connectivity environments. Configuration is cached locally, events are persisted to disk, and a bundled fallback config ensures the SDK functions even on first launch without network access.

Config Resolution Priority

The SDK resolves configuration using a three-tier priority system:

Priority	Source	Description
1 (highest)	Remote (Firestore)	Firestore config, fetched at `configure` (after a failed bootstrap, once a retry of it succeeds), when the TTL elapses and every 15 min in the background
2	Cached (SharedPreferences)	SharedPreferences: the last fetched config, served whatever its age until a fetch replaces it
3 (lowest)	Bundled (assets)	Static `appdna-config.json` included in the app assets

The SDK uses a stale-while-revalidate pattern. Cached config is served immediately, whatever its age, while a fresh copy is fetched from the remote source in the background. If that fetch fails, the cached config stays in use.

Config TTL

The cached configuration has a time-to-live (TTL) that defaults to 3600 seconds (1 hour). You can customize this value in AppDNAOptions:

AppDNA.configure(
    context = this,
    apiKey = "adn_live_xxx",
    environment = Environment.PRODUCTION,
    options = AppDNAOptions(configTTL = 1800L) // 30 minutes
)

When the TTL expires, the SDK fetches a fresh config from Firestore on the next access. The stale config continues to be used until the fresh config is received.

Config Update Notifications

Listen for config updates by collecting the AppDNA.configUpdated coroutine flow:

import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.flow.collect

lifecycleScope.launch {
    AppDNA.configUpdated.collect {
        Log.d("AppDNA", "Config updated — refreshing UI")
        // Re-read remote config values and update UI
    }
}

AppDNA.configUpdated is a SharedFlow<Unit> that emits whenever the SDK applies a new remote config bundle (the fetch at configure, a TTL refresh, the 15-minute background refresh, or refresh() / AppDNA.forceRefreshConfig()). It mirrors iOS’s Notification.Name(AppDNA.configUpdated) and Flutter/RN bridge events.

Cache Keys

The SDK persists configuration data in SharedPreferences under the namespace ai.appdna.sdk. Per-module keys are isolated so partial failures (e.g., paywall config update mid-fetch) cannot leak state across modules:

Key	Description
`cache_flags`	Feature flag configuration
`cache_experiments`	Experiment definitions (variants, weights, salt); assignments are computed, not stored
`cache_surveys`	Survey configuration
`cache_paywalls`	Paywall templates and products
`cache_onboarding`	Onboarding flow definitions
`cache_messages`	In-app message definitions

Bundled Config

For first-launch scenarios or environments with no network access, include a static configuration file in your app assets:

In the AppDNA Console, open Settings → SDK → Config Bundle. The bundle is regenerated automatically shortly after each publish (usually within about 20 seconds); click Regenerate only if you need it at once.
Click JSON Only. It saves appdna-config.json in the form the SDK reads. To download it in CI instead, see Config Bundles in CI/CD.
Place the file at src/main/assets/appdna-config.json.

app/
  src/main/assets/
    appdna-config.json    <-- Add this file

Access the current bundled config version programmatically:

val version = AppDNA.currentBundleVersion

The bundled config is a snapshot and will become stale over time. Always ensure the SDK can reach the remote config source for the latest configuration. The bundled config should be treated as a fallback only.

Event Queue

Events tracked with AppDNA.track(...) are not sent immediately. They are queued locally and flushed in batches.

Queue Behavior

Setting	Default	Description
`flushInterval`	30s	Time interval between automatic flush cycles. When not set, the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`batchSize`	100 (not set)	A cap on the adaptive batch size (see Adaptive Batch Sizing): 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.

Events are flushed on the timer, when the app goes to the background or returns to the foreground, and when the queue reaches the batch size (the adaptive size below, capped by batchSize when set) — whichever comes first. You can also call AppDNA.flush() to trigger an immediate flush.

Persistence

Events are persisted to disk immediately when tracked. This ensures that:

Events survive app crashes and force quits.
Events survive app restarts and device reboots.
Events are delivered on the next successful flush after connectivity is restored.

The event queue is stored in a local SQLite database under the SDK’s private namespace. Events stay queued until they are delivered or dropped: a batch rejected with a 4xx other than 408 or 429, the oldest events beyond 10,000 events or 5 MB, events older than 7 days, and every queued event when analytics consent is revoked. See When Events Are Dropped. Apps upgrading from older SDK versions automatically migrate legacy SharedPreferences-backed event queues on first launch. Going back to an older SDK keeps the queued events only when that version is 1.0.54 or later; it rebuilds a table it cannot use and counts those events as dropped. Going back to 1.0.53 or earlier, the SDK cannot open the newer event database, so events are not recorded until the app is updated again.

Adaptive Batch Sizing

The SDK automatically adjusts batch size based on network conditions reported by ConnectivityManager.NetworkCapabilities:

Wi-Fi or Ethernet: 100 events per batch, even when the network is metered
Metered cellular (most mobile plans): 20 events per batch
Unmetered cellular: 50 events per batch

With batchSize set, the batch size is the smaller of this size and batchSize.

Event Storage Limits

Events are stored locally with the following limits:

Maximum 10,000 events in queue
Maximum 5 MB of queued events: each event’s JSON plus one byte, the same measure as iOS. The SQLite database file is larger — it also holds its indexes and free pages

Oldest events are dropped when limits are exceeded — over 5 MB, the oldest 10 % at a time until the rest fit — and every dropped event is counted. An event older than 7 days is dropped unsent.

Networking

OkHttp Timeouts

The SDK uses OkHttp3 for all HTTP requests with the following timeout configuration:

Timeout	Duration	Description
Connect	30s	Maximum time to establish a connection (10s for background uploads)
Read	30s	Maximum time to read a response
Write	30s	Maximum time to write a request

Retry Strategy

When a flush attempt fails, the SDK retries with exponential backoff:

Attempt	Delay	Description
1	1s	First retry after initial failure
2	2s	Second retry
3	4s	Third and final retry

After 3 failed attempts, the request is abandoned and events remain in the queue for the next flush cycle.

Error Handling

Status Code	Behavior
2xx	Success. Events removed from queue.
408, 429	Events kept in queue and retried with backoff.
401, 403	Invalid or revoked API key. Batch discarded and uploads paused (see Circuit Breaker).
Other 4xx	Client error. Batch discarded (no retry).
5xx	Server error. Events kept in queue and retried.
Network error	Events kept in queue and retried on next flush cycle.

Events that receive a 4xx response other than 408 or 429 are discarded permanently. This prevents malformed events from blocking the queue. Check your event schemas if you see 4xx errors in the SDK logs.

Circuit Breaker

After 5 consecutive upload failures, event uploads are paused: the timer, the batch size and backgrounding do not start an upload (backgrounding schedules no OS background upload, and one already scheduled uploads nothing while paused). Returning to the foreground or calling AppDNA.flush() resets the failure count and resumes uploads. A single failure does not pause uploads, except a 401 or 403 (an invalid or revoked API key): every later batch would be rejected the same way, so it pauses uploads at once, in the in-app queue and the OS background upload alike. Every other failed flush counts toward the consecutive-failure total — whether a 4xx batch was dropped or a 5xx/network error left the batch queued for retry — and only the 5th failure in a row trips the circuit breaker. An OS background upload ends its run after a rejected batch; its next run sends the events behind it.

Request Headers

All requests include the following headers:

Header	Value
`x-api-key`	`{apiKey}`
`Content-Type`	`application/json`
`User-Agent`	`AppDNA-Android-SDK/{sdk_version} (Android {os_release})`

When analytics consent is set to false:

AppDNA.setConsent(analytics = false)

Events are silently dropped and are not added to the queue. No data is stored or transmitted. When consent is later granted, only events tracked after that point are queued and sent.

Consent state is persisted in SharedPreferences. If a user revokes consent and restarts the app, the SDK remembers the revoked state and continues to drop events until consent is explicitly granted again.

Secure Storage

The following data is stored using Android’s EncryptedSharedPreferences (Android Keystore-backed) for security:

Data	Storage	Description
Push tokens	EncryptedSharedPreferences	FCM device token
User IDs	EncryptedSharedPreferences	Identified user ID
Anonymous IDs	EncryptedSharedPreferences	Auto-generated anonymous identifier

EncryptedSharedPreferences uses AES-256-GCM via the Android Keystore, so these values are protected by hardware encryption on supported devices.

Device Identification

The SDK generates an anonymous identifier as a random UUID on first launch and persists it in secure storage. It is not derived from Settings.Secure.ANDROID_ID or any device hardware identifier. The anonymous ID is preserved across AppDNA.reset() — reset() clears only the identified user ID and user traits, leaving the anonymous ID (and its event attribution) intact.

Coroutine Scopes

The SDK uses Kotlin coroutines with the following dispatcher assignments:

Scope	Dispatcher	Used For
IO	`Dispatchers.IO`	Networking, file I/O, SharedPreferences
Main	`Dispatchers.Main`	UI operations, billing callbacks
Default	`Dispatchers.Default`	CPU-bound work (e.g., experiment bucketing, hash)

All SDK operations are non-blocking. Network requests and persistence operations run on the IO dispatcher, while UI-related callbacks (billing flows, paywall/onboarding rendering) are dispatched on the Main thread.

Summary

Concern	Behavior
Config on first launch	Bundled `appdna-config.json` used as fallback
Config caching	SharedPreferences; served whatever its age, refetched once older than `configTTL` (default 3600 s)
Config freshness	Stale-while-revalidate; re-fetched when the TTL elapses, every 15 min by `ConfigRefreshWorker` and on `refresh()` — no real-time listener
Event persistence	Written to disk immediately, survives crashes and restarts
Event flush	Automatic on timer (30s), on background / foreground, or at the adaptive batch size (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), or at `batchSize` when that is smaller (your `batchSize`, else the bootstrap’s value; 100 today, so nothing is capped)
Retry	Up to 3 retries with exponential backoff (1s, 2s, 4s)
4xx errors	Batch discarded, no retry (408 and 429 are retried like a 5xx)
5xx / network errors	Events retained, retried with backoff and on the next flush
Circuit breaker	After 5 consecutive failures, uploads paused until the next foreground or `AppDNA.flush()`
Consent revoked	Queued events deleted; new events not queued
Sensitive data	Stored in EncryptedSharedPreferences (push tokens, user IDs, anon IDs)

Next Steps

Review the full API Reference for all available methods
Learn about Push Notifications for offline token handling
See the Remote Config guide for caching strategies

​Config Resolution Priority

​Config TTL

​Config Update Notifications

​Cache Keys

​Bundled Config

​Event Queue

​Queue Behavior

​Persistence

​Adaptive Batch Sizing

​Event Storage Limits

​Networking

​OkHttp Timeouts

​Retry Strategy

​Error Handling

​Circuit Breaker

​Request Headers

​Consent and Offline Behavior

​Secure Storage

​Device Identification

​Coroutine Scopes

​Summary

​Next Steps

Config Resolution Priority

Config TTL

Config Update Notifications

Cache Keys

Bundled Config

Event Queue

Queue Behavior

Persistence

Adaptive Batch Sizing

Event Storage Limits

Networking

OkHttp Timeouts

Retry Strategy

Error Handling

Circuit Breaker

Request Headers

Consent and Offline Behavior

Secure Storage

Device Identification

Coroutine Scopes

Summary

Next Steps