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 real-time listener for live configuration
2	Cached (SharedPreferences)	SharedPreferences-backed cache with TTL-based expiration
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 while a fresh copy is fetched from the remote source in the background.

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 (initial load, TTL refresh, or live Firestore push). 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 assignments and variants
`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, navigate to SDK > Config Bundle.
Download the appdna-config.json file.
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
`batchSize`	20	Number of events to batch before auto-flushing

Events are flushed when either condition is met (whichever occurs 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 remain queued until they are successfully delivered to the AppDNA backend or the user revokes analytics consent. Apps upgrading from older SDK versions automatically migrate legacy SharedPreferences-backed event queues on first launch.

Adaptive Batch Sizing

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

Wi-Fi: 100 events per batch
Cellular: 50 events per batch
Metered cellular (roaming / data saver): 20 events per batch

Event Storage Limits

Events are stored locally with the following limits:

Maximum 10,000 events in queue
Maximum 5MB disk usage

Oldest events are dropped when limits are exceeded.

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.
4xx	Client error. Events discarded immediately (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 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 until the next app session (a foreground event resets the failure count and resumes uploads). A single failure does not pause uploads. Every 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.

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 with configurable TTL (default 3600s / 1 hour)
Config freshness	Stale-while-revalidate; Firestore real-time listener
Event persistence	Written to disk immediately, survives crashes and restarts
Event flush	Automatic on timer (30s) or batch threshold (20 events)
Retry	Up to 3 retries with exponential backoff (1s, 2s, 4s)
4xx errors	Events discarded, no retry
5xx / network errors	Events retained, retried on next flush
Circuit breaker	After 5 consecutive failures, uploads paused until next session
Consent revoked	Events dropped silently, 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