Configure the CMAB cache for the Flutter SDK
Prerequisites
- Flutter SDK version v3.4.0+.
- A CMAB-enabled experiment in your Optimizely Feature Experimentation project.
Important
To retrieve a CMAB decision, you must use the decideAsync method. The decide method does not fetch CMAB decisions to avoid blocking the user.
Minimum SDK version
3.4.0
Description
When a user is bucketed into a CMAB experiment, the Flutter SDK makes an API call to the CMAB service to determine which variation to show. To improve performance and reduce latency, the SDK caches these decisions based on the following:
- User ID
- Experiment ID
- CMAB attribute values
The cache is automatically invalidated when CMAB attributes change for a user, ensuring fresh decisions when context changes.
By default, the Flutter SDK uses an in-memory Least Recently Used (LRU) cache with a maximum size of 100 entries and a TTL of 30 minutes (1800 seconds). You can customize these settings.
Configuration options
Configure CMAB caching when initializing your client using CmabConfig class.
Default configuration
The Flutter SDK uses the following default values when no custom configuration is provided:
Setting | Default Value | Description |
|---|---|---|
Cache Size | 100 | Maximum number of cached decisions. |
Cache TTL | 1800 seconds (30 minutes) | Time-to-live for cache entries. |
Cache Implementation | LruCache | Thread-safe in-memory Least Recently Used (LRU) cache. |
Examples
Basic configuration
Adjust cache size and TTL for your application's needs.
import 'package:optimizely_flutter_sdk/optimizely_flutter_sdk.dart';
try {
// Initialize SDK with default CMAB configuration
// Default cache size: 100, cache timeout: 1800 seconds (30 minutes)
var flutterSDK = OptimizelyFlutterSdk(
SDK_KEY,
cmabConfig: CmabConfig(), // Uses defaults
);
var response = await flutterSDK.initializeClient();
if (!response.success) {
print('Failed to initialize SDK: ${response.reason}');
return;
}
print('✓ SDK initialized successfully');
// Create user context with attributes
// CMAB uses these attributes to make personalized decisions
var userContext = await flutterSDK.createUserContext(
userId: 'user_123',
attributes: {
'country': 'us'
},
);
if (userContext == null) {
print('Failed to create user context');
return;
}
print('✓ User context created for user_123');
// Use decideAsync for CMAB-enabled flag
// This makes an async call to the CMAB service for personalized variation
// Always use ignoreUserProfileService with CMAB to get correct decisions
print('\nMaking async decision for flag: $CMAB_FLAG_KEY');
var decision = await userContext.decideAsync(
CMAB_FLAG_KEY,
{OptimizelyDecideOption.ignoreUserProfileService},
);
} catch (e) {
print('Error in basicCmabExample: $e');
}Cache behavior
Automatic cache invalidation
The cache is automatically invalidated when:
- The cached entry's TTL expires.
- CMAB attribute values change for a user (detected through MD5 hash comparison).
- The ignoreCmabCache decide option is used.
- The invalidateUserCmabCache decide option is used.
- The resetCmabCache decide option is used.
CMAB-specific decide options
Control cache behavior on a per-decision basis using decide options.
import 'package:optimizely_flutter_sdk/optimizely_flutter_sdk.dart';
// Ignore cache for this decision (always fetch fresh)
var decision = await userContext.decideAsync(
CMAB_FLAG_KEY,
{
OptimizelyDecideOption.ignoreCmabCache
},
);
// Invalidate cached decision for this user and experiment
var decision = await userContext.decideAsync(
CMAB_FLAG_KEY,
{
OptimizelyDecideOption.invalidateUserCmabCache
},
);
// Clear entire CMAB cache
var decision = await userContext.decideAsync(
CMAB_FLAG_KEY,
{
OptimizelyDecideOption.resetCmabCache
},
);
// Combine multiple options
var decision = await userContext.decideAsync(
CMAB_FLAG_KEY,
{
OptimizelyDecideOption.resetCmabCache, OptimizelyDecideOption.includeReasons
},
);Available CMAB decide options
Decide option | Description |
|---|---|
ignoreCmabCache | Bypass cache and fetch a fresh decision from CMAB service. |
invalidateUserCmabCache | Remove cached decision for this user and experiment before deciding. |
resetCmabCache | Clear all entries from the CMAB cache before deciding. |