iOS Offline Support

Supported on: iOS SDK 1.0.61+

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 3600 seconds (1 hour). You can customize this value in AppDNAOptions:

AppDNA.configure(
    apiKey: "adn_live_xxx",
    environment: .production,
    options: AppDNAOptions(configTTL: 1800) // 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 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
}

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

Events are flushed when either condition is met (whichever occurs first).

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 Application Support directory. Events remain queued until they are successfully delivered to the AppDNA backend or the user revokes analytics consent.

Adaptive Batch Sizing

The SDK automatically adjusts batch size based on network conditions:

Wi-Fi: 100 events per batch
Cellular: 50 events per batch
Expensive cellular (roaming): 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.

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.

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.

Network Timeouts

Operation	Timeout
API requests	30s
Resource downloads	60s

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. 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

Keychain storage ensures these values persist across app reinstalls and are protected by the device’s hardware encryption.

Summary

Concern	Behavior
Config on first launch	Bundled `appdna-config.json` used as fallback
Config caching	UserDefaults with configurable TTL (default 3600s)
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)

​Config Resolution Priority

​Config TTL

​Config Update Notifications

​Bundled Config

​Event Queue

​Queue Behavior

​Persistence

​Adaptive Batch Sizing

​Event Storage Limits

​Retry Policy

​Error Handling

​Circuit Breaker

​Network Timeouts

​Consent and Offline Behavior

​Secure Storage

​Summary

Config Resolution Priority

Config TTL

Config Update Notifications

Bundled Config

Event Queue

Queue Behavior

Persistence

Adaptive Batch Sizing

Event Storage Limits

Retry Policy

Error Handling

Circuit Breaker

Network Timeouts

Consent and Offline Behavior

Secure Storage

Summary