diff --git a/website/docs/sdk-reference/dart.mdx b/website/docs/sdk-reference/dart.mdx index 65de1eae..3aa13a46 100644 --- a/website/docs/sdk-reference/dart.mdx +++ b/website/docs/sdk-reference/dart.mdx @@ -41,7 +41,7 @@ Or put the following directly to your `pubspec.yml` and run `dart pub get` or `f ```yaml title="pubspec.yml" dependencies: - configcat_client: ^4.0.0 + configcat_client: ^5.0.0 ``` ### 2. Import the ConfigCat SDK @@ -425,18 +425,18 @@ client.forceRefresh(); The SDK provides several hooks (events), by means of which you can get notified of its actions. You can subscribe to the following events emitted by the _ConfigCat_ client: -- `onClientReady()`: This event is emitted when the client reaches the ready state, i.e. completes initialization. +- `onClientReady(ClientCacheState)`: This event is emitted when the client reaches the ready state, i.e. completes initialization. The `cacheState` argument indicates the state of the internal cache at the time the client became ready. * If Lazy Loading or Manual Polling is used, it's considered ready right after instantiation. * If Auto Polling is used, the ready state is reached as soon as * the initial sync with the external cache yields up-to-date config data, * otherwise, if the client is online (i.e. HTTP requests are allowed), the first config fetch operation completes (regardless of success or failure), * or the time specified via Auto Polling's `maxInitWaitTime` option has passed. - Reaching the ready state usually means the client is ready to evaluate feature flags and settings. - However, please note that this is not guaranteed. In case of initialization failure or timeout, the internal cache - may be empty or expired even after the ready state is reported. Alternatively, in Auto Polling mode, you can wait for - the first `onConfigChanged` event to be notified when the internal cache is actually populated with config data. -- `onConfigChanged(Map)`: This event is emitted first when the client's internal cache gets populated. + Reaching the ready state usually means the client is ready to evaluate feature flags and settings. + However, please note that this is not guaranteed. In case of initialization failure or timeout, + the internal cache may be empty or expired even after the ready state is reported. + You can verify this by checking the `ClientCacheState` argument. +- `onConfigChanged(Map, ConfigCatClientSnapshot)`: This event is emitted first when the client's internal cache gets populated. Afterwards, it is emitted again each time the internally cached config is updated to a newer version, either as a result of synchronization with the external cache, or as a result of fetching a newer version from the ConfigCat CDN. - `onFlagEvaluated(EvaluationDetails)`: This event is emitted each time the client evaluates a feature flag or setting. @@ -463,6 +463,82 @@ or with the `hooks` property of the ConfigCat client: client.hooks.addOnFlagEvaluated((details) => /* handle the event */); ``` +## Snapshots and synchronous feature flag evaluation + +The _ConfigCat_ client doesn't directly provide synchronous methods for evaluating feature flags and settings because +such synchronous methods could block the executing thread for longer periods of time (e.g. when downloading config data +from the ConfigCat CDN servers), which could lead to an unresponsive application. + +However, there can be circumstances where synchronous evaluation is preferable, thus, since `v5.0.0`, the Dart SDK provides a way +to synchronously evaluate feature flags and settings as a non-blocking operation, via _snapshots_. + +Using the `snapshot()` method, you can capture the current state of the _ConfigCat_ client (including the latest downloaded config data) +and use the resulting snapshot object to synchronously evaluate feature flags and settings based on the captured state: + +```dart +final client = ConfigCatClient.get( + sdkKey: '#YOUR-SDK-KEY#', + options: ConfigCatOptions(pollingMode: PollingMode.autoPoll()) +); + +await client.waitForReady(); + +final snapshot = client.snapshot(); + +final user = ConfigCatUser(identifier: '#UNIQUE-USER-IDENTIFIER#'); +for (var key in snapshot.getAllKeys()) { + final value = snapshot.getValue(key: key, defaultValue: null, user: user); + print('$key: $value'); +} +``` + +Creating a snapshot is a cheap operation. This is possible because snapshots capture the client's internal (in-memory) cache. +No attempt is made to refresh the internal cache, even if it's empty or expired. + +:::caution +Please note that creating and using a snapshot +* won't trigger synchronization with the external cache when working with [shared caching](../advanced/caching.mdx#shared-cache), +* won't fetch the latest config data from the ConfigCat CDN when the internally cached config data is empty or expired. +::: + +For the above reasons, it's recommended to use snapshots in conjunction with the Auto Polling mode, where the SDK automatically +updates the internal cache in the background. (For other polling modes, you'll need to manually initiate a cache refresh +by calling `forceRefresh`.) + +Because of this behavior, it's important to make sure that the client has completed initialization and populated its internal cache +before creating snapshots. Otherwise the snapshot's evaluation methods won't have the data to do actual evaluation, +but will just return the default value you pass to them. Which behavior is usually not what you want in your application. + +In Auto Polling mode, you can use the `waitForReady` method to wait for the latest config data to become available locally. +This is an asynchronous operation, which completes as soon as the client reaches the ready state, i.e. completes initialization +(or the time specified via the `maxInitWaitTime` option passes). + +(Please note that this doesn't apply to other polling modes. In those cases, the client doesn't contact the ConfigCat CDN +during initialization, so the ready state is reached as soon as the first sync with the external cache completes.) + +Typically, you call `waitForReady` and wait for its completion only once, in the startup phase of your application. + +:::caution +Reaching the ready state usually means the client is ready to evaluate feature flags and settings. +However, please note that this is not guaranteed. In case of initialization failure or timeout, the internal cache +may be empty or expired even after the ready state is reported. You can verify this by checking the return value. +::: + +```dart +final clientCacheState = await client.waitForReady(); +if (clientCacheState == ClientCacheState.noFlagData) { + // Handle initialization failure (see below). +} +``` + +You have the following options to handle unsuccessful initialization: +* If it's acceptable for your application to start up and use the default values passed to the evaluation methods, + you may log some warning (or skip the check altogether as the client will log warnings anyway), and let the application continue. +* Otherwise, you need to either terminate the application or continue waiting. The latter is an option because the client + might be able to obtain the config data later, in the case of a transient problem like some temporary network issue. + However, the _ConfigCat SDK_ doesn't provide out-of-the-box support for this case currently. You can implement this logic by + subscribing to the `onConfigChanged` hook and waiting for the first event. + ## Online / Offline mode In cases when you'd want to prevent the SDK from making HTTP calls, you can put it in offline mode: