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 config, fetched at `configure` (after a failed bootstrap, once a retry of it succeeds) and again when the TTL elapses
2	Cached	UserDefaults: the last fetched config, served whatever its age until a fetch replaces it
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, 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(
    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, 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.
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. When not set, the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`batchSize`	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.

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

Adaptive Batch Sizing

The SDK automatically adjusts batch size based on network conditions:

Wi-Fi or wired: 100 events per batch, whether or not iOS marks the connection expensive
Cellular marked expensive: 20 events per batch. iOS marks every cellular connection expensive, so this is the cellular case in practice
Cellular not marked expensive: 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 a line break. Sent and dropped events stay in the file until the SDK reclaims their space — once they pass 1 MB, or outweigh the queued ones — so the file itself can reach about 6 MB

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. A launch before the device is first unlocked (a background launch) cannot read the queue: the SDK leaves it as it is and reads it as soon as it can, so nothing queued is dropped or sent twice by mistake.

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

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; served whatever its age, refetched once older than `configTTL` (default 3600 s)
Config freshness	Stale-while-revalidate; re-fetched when the TTL elapses 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
Consent revoked	Queued events deleted; new events 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