From ed96ca27157d4bd34dc80e13bc1aff49f7d8f92c Mon Sep 17 00:00:00 2001
From: Fabrizio Demaria <fabrizio.f.demaria@gmail.com>
Date: Mon, 15 Jan 2024 21:49:51 +0100
Subject: [PATCH] docs: Add docs on initialization strategy config (#116)

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..48df2829 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. After that, the Provider will try to refresh the cache on disk for the future session, without impacting the current session.
 
 ### Changing context after the provider initialization 
 The evaluation context can be changed during the app session using `setEvaluationContext(...)`.