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 real-time listener for live configuration |
| 2 | Cached | UserDefaults-backed cache with TTL-based expiration |
| 3 (lowest) | Bundled | Static appdna-config.json included in the app bundle |
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 300 seconds (5 minutes). You can customize this value in AppDNAOptions:
AppDNA.configure(
apiKey: "adn_live_xxx",
environment: .production,
options: AppDNAOptions(configTTL: 600) // 10 minutes
)
Config Update Notifications
Listen for config updates using NotificationCenter:
NotificationCenter.default.addObserver(
forName: AppDNA.configUpdated,
object: nil,
queue: .main
) { notification in
print("Config updated — refreshing UI")
// Re-read remote config values and update UI
}
Bundle Version
Check the current config bundle version:
let version = AppDNA.currentBundleVersion // Int
print("Current config bundle version: \(version)")
Bundled Config
For first-launch scenarios or environments with no network access, include a static configuration file in your app bundle:
- In the AppDNA Console, navigate to SDK > Config Bundle.
- Download the
appdna-config.json file.
- Add the file to your Xcode project, ensuring it is included in your app target’s Copy Bundle Resources build phase.
MyApp/
Resources/
appdna-config.json <-- Add this file
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 |
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 the app’s documents directory. Events remain queued until they are successfully delivered to the AppDNA backend or the user revokes analytics consent.
Retry Policy
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.
Network Timeouts
| Operation | Timeout |
|---|
| API requests | 30s |
| Resource downloads | 60s |
Consent and Offline Behavior
When analytics consent is set to false:
AppDNA.setConsent(analytics: false)
Consent state is persisted. 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 in the iOS Keychain for security:
| Data | Storage | Description |
|---|
| Push tokens | Keychain | APNs device token |
| User IDs | Keychain | Identified user ID |
| Anonymous IDs | Keychain | Auto-generated anonymous identifier |
Summary
| Concern | Behavior |
|---|
| Config on first launch | Bundled appdna-config.json used as fallback |
| Config caching | UserDefaults with configurable TTL (default 300s) |
| 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 |
| Consent revoked | Events dropped silently, not queued |
| Sensitive data | Stored in Keychain (push tokens, user IDs, anonymous IDs) |
