Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 83 additions & 7 deletions website/docs/sdk-reference/dart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<string, Setting>)`: 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<string, Setting>, 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.
Expand All @@ -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<dynamic>(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:
Expand Down
Loading