Flutter Offline Support

Supported on: iOS SDK 1.0.61+ · Android SDK 1.0.33+ · Flutter SDK 1.0.3+

The AppDNA Flutter SDK is designed to work reliably in offline and poor network conditions. Config caching, event queuing, and bundled fallback configs all happen at the native layer (iOS UserDefaults + Application Support; Android SharedPreferences + SQLite) for crash-safe persistence. This page documents the behavior end-to-end; for additional platform-specific internals see the iOS Offline and Android Offline guides.

Config Resolution Priority

When the SDK needs configuration data, it follows a three-tier priority order:

Priority	Source	Description
1 (highest)	Remote	Firestore config, fetched by the native SDK at `configure` (after a failed bootstrap, once a retry of it succeeds) and when the TTL elapses
2	Cached	UserDefaults (iOS) / SharedPreferences (Android): the last fetched config, served whatever its age until a fetch replaces it
3 (lowest)	Bundled	Static `appdna-config.json` shipped with the app binary

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:

await AppDNA.configure(
  apiKey: "adn_live_xxx",
  env: AppDNAEnvironment.production,
  options: AppDNAOptions(
    configTTL: 1800, // 30 minutes
  ),
);

Parameter	Type	Default	Description
`configTTL`	`int?`	`3600`	Seconds before cached config is considered stale

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

The native layer emits a notification whenever the SDK applies a new remote config bundle (the fetch at configure, a TTL refresh, or refresh(); on Android also the 15-minute background refresh). Use AppDNA.remoteConfig.onChanged to react in Flutter:

AppDNA.remoteConfig.onChanged(() {
  // Config updated — re-read remote values and refresh UI
});

This mirrors iOS’s Notification.Name(AppDNA.configUpdated) and Android’s AppDNA.configUpdated SharedFlow<Unit>.

Bundled Config

To ensure the SDK has a valid configuration on first launch — even without network connectivity — you can bundle a static config file with your app. Download it from the AppDNA Console with JSON Only under 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), or in CI as in Config Bundles in CI/CD. The native SDK reads the file, so it goes in the native locations below, not under flutter: assets: in pubspec.yaml.

iOS

Add the config file to your Xcode project bundle:

Save the downloaded file as appdna-config.json.
Add it to your Xcode project by dragging it into the project navigator.
Ensure the file is included in your target’s Build Phases > Copy Bundle Resources.

Android

Place the config file in the Android assets directory:

android/app/src/main/assets/appdna-config.json

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 — download it again as part of your CI/CD pipeline before each release (the server regenerates it shortly after each publish).

Bundle Versioning

The native SDK reads bundle_version from the file. When it is greater than 0, the SDK sends it in the device context of every event, so you can see which bundle a build carries. The SDK does not compare versions: it fetches remote config at configure and when the TTL elapses, whatever the file holds. The file fills only the sections the cache does not have, except screen_index and, on iOS, brand (see Three-Tier Config Priority); a remote fetch replaces it.

Event Queue

Events tracked with AppDNA.track(...) are not sent immediately. They are queued locally on the native side 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. You can also call AppDNA.flush() to trigger an immediate flush.

await AppDNA.configure(
  apiKey: "adn_live_xxx",
  env: AppDNAEnvironment.production,
  options: AppDNAOptions(
    flushInterval: 30, // Seconds between automatic flushes
    batchSize: 50,     // At most 50 events per upload; fewer on a slower network
  ),
);

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.

On iOS, the event queue is stored in the app’s Application Support directory. On Android, events are stored in a local SQLite database under the SDK’s private namespace. 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, even when the connection is expensive or metered
Cellular marked expensive (iOS) or metered (Android): 20 events per batch. iOS marks every cellular connection expensive; most Android mobile plans are metered
Other cellular: 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, on both platforms measured the same way: each event’s JSON plus one byte. On iOS, sent and dropped events stay in the queue file until the SDK reclaims their space (once they pass 1 MB, or outweigh the queued ones), so the file can reach about 6 MB; on Android, the SQLite database file also holds its indexes and free pages

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. On iOS, 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.

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

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

await 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 on the native side (UserDefaults on iOS, SharedPreferences on Android). 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 securely on each platform:

Data	iOS Storage	Android Storage	Description
Push tokens	Keychain	EncryptedSharedPreferences	APNs / FCM device token
User IDs	Keychain	EncryptedSharedPreferences	Identified user ID
Anonymous IDs	Keychain	EncryptedSharedPreferences	Auto-generated anonymous identifier

On iOS, Keychain storage ensures these values persist across app reinstalls and are protected by the device’s hardware encryption. On Android, EncryptedSharedPreferences uses AES-256-GCM via the Android Keystore, so values are protected by hardware encryption on supported devices.

EventChannel Streams

The SDK uses Flutter EventChannels to stream real-time data from the native layer. These streams work across the full app lifecycle, including when the app transitions between foreground and background states:

EventChannel	Purpose
`com.appdna.sdk/web_entitlement`	Web entitlement change stream
`com.appdna.sdk/events/push`	Push notification delegate events
`com.appdna.sdk/events/paywall`	Paywall delegate events
`com.appdna.sdk/events/onboarding`	Onboarding delegate events
`com.appdna.sdk/events/in_app_message`	In-app message delegate events
`com.appdna.sdk/events/survey`	Survey delegate events
`com.appdna.sdk/events/deep_link`	Deep link delegate events
`com.appdna.sdk/events/screen`	Server-driven screen delegate events

EventChannel streams automatically reconnect when the app returns from the background. You do not need to re-subscribe to streams after lifecycle transitions.

Offline Behavior Summary

Concern	Behavior
Config on first launch	Bundled `appdna-config.json` used as fallback
Config caching	Native storage; served whatever its age, refetched once older than `configTTL` (default 3600 s)
Config freshness	Stale-while-revalidate; re-fetched by the native SDK when the TTL elapses and on `refresh()` (on Android also every 15 min in the background) — 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
Circuit breaker	After 5 consecutive failures, uploads paused until the next foreground or `AppDNA.flush()`
Consent revoked	Queued events deleted; new events not queued
Feature flags	Uses cached / bundled values until remote config is refreshed
Experiments	Experiment definitions are cached; variants are assigned on the device, offline too
Push registration	Token registration is retried when connectivity is restored
Purchases	Handled by the native store SDK (StoreKit / Play Billing)
Sensitive data	Keychain (iOS) / EncryptedSharedPreferences (Android)

Best Practices

Always bundle a config file for first-launch reliability.
Keep configTTL reasonable — 1 hour (default) balances freshness with network efficiency.
Call flush() before background — While the SDK handles this automatically, explicitly flushing before the app enters the background provides an extra safety net.
Do not assume network availability — Design your app UI to work with cached config values. onReady() fires once the bootstrap has succeeded or failed, without waiting for the remote config: the fetch starts when the bootstrap succeeds (after a failure, when a retry succeeds) — use remoteConfig.onChanged to pick up the fetched values.

// Flush events before background
void onAppLifecycleStateChanged(AppLifecycleState state) {
  if (state == AppLifecycleState.paused) {
    AppDNA.flush();
  }
}

​Config Resolution Priority

​Config TTL

​Config Update Notifications

​Bundled Config

​iOS

​Android

​Bundle Versioning

​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

​EventChannel Streams

​Offline Behavior Summary

​Best Practices

Config Resolution Priority

Config TTL

Config Update Notifications

Bundled Config

iOS

Android

Bundle Versioning

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

EventChannel Streams

Offline Behavior Summary

Best Practices