Supported on: Android SDK 1.0.33+
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
)
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
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 |
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 |
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. Server errors (4xx) immediately pause uploads for the current session.
All requests include the following headers:
| Header | Value |
|---|
Authorization | Bearer {apiKey} |
Content-Type | application/json |
User-Agent | AppDNA-Android/{sdk_version} |
Consent and Offline Behavior
When analytics consent is set to false:
AppDNA.setConsent(analytics = false)
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 |
Device Identification
The SDK derives a stable per-install identifier using Settings.Secure.ANDROID_ID combined with the SDK-generated anonymous ID. The anonymous ID is regenerated on AppDNA.reset(); ANDROID_ID is unique per app per device and persists across app reinstalls on the same device (unless the device is factory reset).
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
