Offline Support

Koolbase caches your feature flags, remote config, and version policy locally so your app works even when there is no network connection.

What gets cached

On the first successful SDK init, the bootstrap snapshot is persisted to local storage using shared_preferences. This snapshot includes:

Feature flagsAll flag keys and their current evaluated values

Remote configAll config keys and values

Version policyMinimum version, update mode, message, and store URL

What is not cached

Database records, storage files, auth sessions, and function responses are not cached by the SDK. Only the bootstrap payload (flags, config, version policy) is cached for offline use.

First launch with no network

On the very first launch, if there is no network connection and no cached snapshot exists, the SDK initialises with empty state. All flag checks return null (or the fallback if you use ?? false) and all config reads return their fallback values.

This means your app will work on the very first launch offline — as long as you have defined sensible fallbacks for every flag and config key.

lib/main.dartDart

// SDK init — safe even with no network
await Koolbase.init(apiKey: 'pk_live_...');
// If no network and no cache: flags={}, config={}, version=null

// These will all return fallbacks safely
final show = Koolbase.flags['new_ui'] ?? false;          // false
final url  = Koolbase.config.getString('api_url',
  fallback: 'https://api.myapp.com');                    // fallback
final ver  = await Koolbase.version.check();             // upToDate

Cache refresh

The SDK refreshes the cache in the background on a polling interval (default: 60 seconds). When a fresh snapshot is fetched, the in-memory state and the local cache are both updated atomically. Flag and config reads after the refresh return the latest values.

lib/main.dartDart

// Customise polling interval (optional)
await Koolbase.init(
  apiKey: 'pk_live_...',
  pollingInterval: const Duration(seconds: 30), // poll every 30s
);

// Disable polling (manual refresh only)
await Koolbase.init(
  apiKey: 'pk_live_...',
  pollingInterval: Duration.zero,
);

// Manually trigger a refresh
await Koolbase.refresh();

Cache TTL

The cached snapshot does not expire automatically. If the app is launched offline, the last known snapshot is used regardless of how old it is. This ensures consistent behaviour in poor network conditions — your users always see something rather than a broken state.

Stale cache is better than no cache

A week-old cached snapshot is better than an empty state. Always prefer the cached values as the safe fallback, and let the background refresh bring them up to date when connectivity returns.

Listen for cache updates

If you want to react when new flag or config values arrive from the server, listen to the update stream:

lib/main.dartDart

// Listen for snapshot updates
Koolbase.onUpdate.listen((_) {
  // New flags/config loaded — refresh your UI if needed
  setState(() {});
  print('Koolbase snapshot refreshed');
});