From 1aad71218ba06a3dce5822056fa5f723f57e1ac3 Mon Sep 17 00:00:00 2001
From: Fabrizio Demaria <fdema@spotify.com>
Date: Mon, 15 Jan 2024 16:58:52 +0100
Subject: [PATCH] docs: Add docs on initialization strategy config

Signed-off-by: Fabrizio Demaria <fdema@spotify.com>
---
 README.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 61b7d471..01ce0968 100644
--- a/README.md
+++ b/README.md
@@ -29,12 +29,17 @@ Where `0.1.6` is the most recent version of this SDK. Released versions can be f
 <!---x-release-please-end-->
 
 ### Enabling the provider, setting the evaluation context and resolving flags
+
+Please refer to the OpenFeature Kotlin SDK [documentation](https://github.com/open-feature/kotlin-sdk) for more information on OpenFeature specific APIs mentioned throughout this README (e.g. `setProvider`, `setProviderAndWait`, OpenFeature Events).
+
+Basic usage:
 ```kotlin
 coroutineScope.launch {
     OpenFeatureAPI.setProviderAndWait(
         ConfidenceFeatureProvider.create(
             applicationContext,
-            "<MY_SECRET>"
+            "<MY_SECRET>",
+            initialisationStrategy = InitialisationStrategy.ActivateAndFetchAsync
         ),
         dispatcher = Dispatchers.IO,
         initialContext = ImmutableContext(targetingKey = "myTargetingKey")
@@ -43,9 +48,12 @@ coroutineScope.launch {
 }
 ```
 
-`MY_SECRET` is an API key that can be generated in the [Confidence UI](https://confidence.spotify.com/console).
+Where:
+- `MY_SECRET` is an API key that can be generated in the [Confidence UI](https://confidence.spotify.com/console).
 
-The OpenFeature Event `ProviderReady` is also emitted when the provider is done initializing the cache. For more information on the OpenFeature APIs, follow the related [README](https://github.com/open-feature/kotlin-sdk?tab=readme-ov-file#usage).
+- `initializationStrategy` is set to one of these two options:
+  - **FetchAndActivate** (_default_): when calling `setProvider`/`setProviderAndWait`, the Provider attemtps to refresh the cache from remote and emits the OpenFeature Event `ProviderReady` after such an attempt (regardless of its success)
+  - **ActivateAndFetchAsync**: when calling `setProvider`/`setProviderAndWait`, the Provider emits the OpenFeature Event `ProviderReady` immediately, utilizing whatever cache was saved on disk from the previous session. The Provider will still try to refresh the cache on disk for the future session.
 
 ### Changing context after the provider initialization 
 The evaluation context can be changed during the app session using `setEvaluationContext(...)`.