From 8a49bf558b3c5314cfa6ced13287ceac46ffbfb7 Mon Sep 17 00:00:00 2001 From: Fabrizio Demaria Date: Tue, 6 Feb 2024 16:06:10 +0100 Subject: [PATCH] docs: Update Docs further --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 01483415..20bb7e46 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ For documentation related to flags management in Confidence, refer to the [Confi Functionalities: - Managed integration with the Confidence backend -- Pre-fetch and cache flag evaluations, for fast value reads even when the application is offline +- Prefetch and cache flag evaluations, for fast value reads even when the application is offline - Automatic data collection (in the backend) about which flags have been accessed by the application ## Dependency Setup @@ -69,18 +69,18 @@ There is also an `async/await` compatible API available for waiting the Provider await OpenFeatureAPI.shared.setProviderAndWait(provider: provider) ``` -A ultity function is available on the provider to check if the current storage has any values stored - this can be used to determine the best initialization strategy. +A utility function is available on the provider to check if the current storage has any values stored - this can be used to determine the best initialization strategy. ```swift // If we have no cache, then do a fetch first. -var initializationStratgey: InitializationStrategy = .activateAndFetchAsync +var initializationStrategy: InitializationStrategy = .activateAndFetchAsync if ConfidenceFeatureProvider.isStorageEmpty() { - initializationStratgey = .fetchAndActivate + initializationStrategy = .fetchAndActivate } ``` Initialization strategies: -- _acticateAndFetchAsync_: the flags in the cached are used for this session, while updated values are fetched and stored on disk for a future session; -- _fetchAndActivate_: the Provider attempts to refresh the flag cache on disk before exposing the flags; this might prolongue the time needed for the Provider to become READY. +- _acticateAndFetchAsync_: the flags in the cached are used for this session, while updated values are fetched and stored on disk for a future session; this means that a READY event is immediately emitted when calling `setProvider()`; +- _fetchAndActivate_: the Provider attempts to refresh the flag cache on disk before exposing the flags; this might prolong the time needed for the Provider to become READY. To listen for the _READY_ event, you can add an event handler via the `OpenFeatureAPI` shared instance: ```swift @@ -103,11 +103,13 @@ let ctx = MutableContext(targetingKey: "myNewTargetingKey", structure: MutableSt OpenFeatureAPI.shared.setEvaluationContext(evaluationContext: ctx) ``` -`setEvaluationContext()` is a synchronous function similar to `setProvider()`. It calls the Confidence backend to fetch the flag evaluations according to the new evaluation context; if the call is successful, it replaces the on-device cache with the new flag data. +`setEvaluationContext()` is a synchronous function similar to `setProvider()`. It calls the Confidence backend to fetch the flag evaluations according to the new evaluation context; if the call is successful, it replaces the cache with the new flag data. + +**Note:** the initialization strategy is not taken into consideration when calling `setEvaluationContext()`, so it's required to wait for READY before resuming to resolve flags. **Note:** if you do attempt to resolve a flag before the READY event is emitted, you may receive the default value with reason `STALE`. -**Note:** A "targeting key" in the evaluation context is expected by the Confidence backend where each key gets assigned a different flag's variant (consistently). The `targetingKey` argument is the default place where to provide a targeting key at runtime (as defined by the OpenFeature APIs), but a different custom field inside the `structure` value can also be configured for this purpose in the Confidence portal (making the `targetingKey` argument redundant, i.e. feel free to set it to empty string). +**Note:** a "targeting key" in the evaluation context is expected by the Confidence backend where each key gets assigned a different flag's variant (consistently). The `targetingKey` argument is the default place where to provide a targeting key at runtime (as defined by the OpenFeature APIs), but a different custom field inside the `structure` value can also be configured for this purpose in the Confidence portal (making the `targetingKey` argument redundant, i.e. feel free to set it to empty string). ### Handling Provider Errors