The AppDNA React Native SDK is designed to work seamlessly offline. All offline logic — event queuing, config caching, and retry — is delegated to the native iOS and Android SDKs. The TypeScript layer does not manage any offline state directly.
Architecture
The React Native SDK is a thin wrapper around the native SDKs via NativeModules. When your app is offline:
- Events are queued in native persistent storage
- Cached configuration is served from the native layer
- Queued events are flushed automatically when connectivity is restored
The Promise-based API works seamlessly regardless of network state. Calls resolve based on the native layer’s handling — cached data is returned when available, and events are silently queued for later delivery.
You do not need to add any offline-handling code in your React Native layer. The native SDKs manage all caching, queuing, and retry logic automatically.
Config Priority
The SDK resolves configuration values using the following priority order:
| Priority | Source | Description |
|---|
| 1 | Remote | Freshly fetched from the AppDNA server |
| 2 | Cached | Previously fetched config stored on device |
| 3 | Bundled | Shipped with the app as a fallback |
Configuration Options
Control offline behavior through AppDNAOptions when configuring the SDK:
await AppDNA.configure("adn_live_xxx", "production", {
flushInterval: 30, // Seconds between automatic event flushes
batchSize: 20, // Number of events to batch before flushing
configTTL: 300, // Seconds before cached config is considered stale
});
| Parameter | Type | Default | Description |
|---|
flushInterval | number | 30 | Seconds between automatic event flushes |
batchSize | number | 20 | Number of events to batch before flushing |
configTTL | number | 300 | Seconds before cached config is considered stale |
These values are passed to the native SDK during configuration. Adjusting them does not change any JavaScript-level behavior — all batching and caching is handled natively.
Bundled Config
For true offline-first support on first launch, you can bundle a default configuration with your app. This ensures the SDK has a valid config even if the device has never connected to the AppDNA server.
iOS
Add the bundled config file to your Xcode project:
- Create a file named
appdna-config.json with your default configuration.
- Add it to your Xcode project by dragging it into the project navigator.
- Ensure it is included in the Copy Bundle Resources build phase of your target.
Android
Place the bundled config file in the Android assets directory:
android/app/src/main/assets/appdna-config.json
The bundled config is a static fallback and will not receive updates. It is only used when no cached or remote config is available. Keep it in sync with your server configuration to avoid inconsistencies on first launch.
Event Queue Behavior
Events tracked while offline are stored in a persistent native queue:
- Events are added to the queue when
AppDNA.track(...) is called.
- The native SDK attempts to flush the queue every
flushInterval seconds.
- If the flush fails (no connectivity), events remain in the queue.
- When connectivity is restored, the queue is flushed automatically.
- Calling
AppDNA.flush() forces an immediate flush attempt.
The queue has no hard size limit. Events are persisted to disk, so they survive app restarts and device reboots.
Events are delivered in order. The SDK guarantees that events queued while offline are sent in the same order they were tracked, preserving the correct event timeline.
Lifecycle Handling
The native SDKs manage app lifecycle transitions automatically:
| Event | Behavior |
|---|
| App backgrounded | Queued events are flushed immediately |
| App terminated | Event queue is persisted to disk |
| App foregrounded | Config is refreshed if TTL has expired |
| App cold start | Pending events from the previous session are flushed |
onEntitlementsChanged, onPushReceived) survive app backgrounding. The native layer maintains the listener registrations and re-emits events when the app returns to the foreground.
Unsubscribe Pattern
All event listeners in the React Native SDK return a cleanup function. Always call the cleanup function when the listener is no longer needed:
// Subscribe
const unsubscribe = AppDNA.billing.onEntitlementsChanged((entitlements) => {
console.log("Entitlements changed:", entitlements);
});
// Unsubscribe when component unmounts
unsubscribe();
| Listener | Returns |
|---|
AppDNA.billing.onEntitlementsChanged | () => void |
AppDNA.onWebEntitlementChanged | () => void |
AppDNAPush.onPushReceived | () => void |
AppDNAPush.onPushTapped | () => void |
Failing to call the unsubscribe function will result in memory leaks and stale callbacks. In React components, always clean up in the useEffect return function.
React Hook Pattern
import { useEffect, useState } from 'react';
import { AppDNA } from '@appdna/react-native-sdk';
function useEntitlements() {
const [entitlements, setEntitlements] = useState([]);
useEffect(() => {
// Load initial entitlements
AppDNA.billing.getEntitlements().then(setEntitlements);
// Listen for changes
const unsubscribe = AppDNA.billing.onEntitlementsChanged(setEntitlements);
// Clean up on unmount
return () => unsubscribe();
}, []);
return entitlements;
}
Network Resilience Summary
| Scenario | SDK Behavior |
|---|
| No network on first launch | Bundled config is used; events are queued |
| Network lost mid-session | Cached config continues; events are queued |
| Network restored | Config refreshed if stale; queued events flushed |
| Intermittent connectivity | Automatic retry with exponential backoff |
| App killed while offline | Events persisted to disk; sent on next launch |
The React Native SDK provides fully offline-capable behavior with zero additional code. Configure flushInterval, batchSize, and configTTL to tune performance, and optionally bundle a default config for first-launch scenarios.
