From 5189172d7e6ee3d3cd33def779c650c6ae002eb0 Mon Sep 17 00:00:00 2001 From: Peter Csajtai Date: Fri, 16 Oct 2026 15:09:16 +0200 Subject: [PATCH 1/2] Actualize the Dart SDK docs with snapshot and hooks related changes --- website/docs/sdk-reference/dart.mdx | 90 ++++++++++++++++++++++++++--- 1 file changed, 83 insertions(+), 7 deletions(-) diff --git a/website/docs/sdk-reference/dart.mdx b/website/docs/sdk-reference/dart.mdx index 65de1eae..790ca049 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.2.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: From 8e722d176f78d8edebf219dfee5b8bf26666b7be Mon Sep 17 00:00:00 2001 From: Peter Csajtai Date: Fri, 16 Oct 2026 15:31:22 +0200 Subject: [PATCH 2/2] Update website/docs/sdk-reference/dart.mdx Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> --- website/docs/sdk-reference/dart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/sdk-reference/dart.mdx b/website/docs/sdk-reference/dart.mdx index 790ca049..3aa13a46 100644 --- a/website/docs/sdk-reference/dart.mdx +++ b/website/docs/sdk-reference/dart.mdx @@ -469,7 +469,7 @@ The _ConfigCat_ client doesn't directly provide synchronous methods for evaluati 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.2.0`, the Dart SDK provides a way +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)