docs: update readme

README.md

@@ -4,9 +4,18 @@
 </a>
 
 # Confidence SDK for Android
-This is the Android SDK for Confidence, a feature flagging and Experimentation system developed by Spotify. 
+This is the Android SDK for [Confidence](https://confidence.spotify.com/), a feature flagging and Experimentation system developed by Spotify.
 
-The SDK allows you to consume feature flags and track events from your application.
+It also contains the Confidence OpenFeature Provider, to be used in conjunction with the [Open Feature SDK](https://openfeature.dev/docs/reference/concepts/provider/).
+
+For documentation related to flag management and event tracking in Confidence, refer to [Confidence decumentation website](https://confidence.spotify.com/docs).
+
+Functionalities:
+
+* Managed integration with the Confidence backend
+* Prefetch and cache flag evaluations, for fast value reads even when the application is offline
+* Automatic data collection about which flags have been accessed by the application
+* Event tracking for instrumenting your application
 
 ## Usage
 
@@ -32,10 +41,19 @@ You can create your `Confidence` instance using the `ConfidenceFactory` class li
 val confidence = ConfidenceFactory.create(
     context = app.applicationContext,
     clientSecret = "<MY_SECRET>",
-    region = ConfidenceRegion.EUROPE
+    region = ConfidenceRegion.EUROPE,
+    loggingLevel = LoggingLevel.VERBOSE
 )
 ```
-Where `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 `loggingLevel` sets the verbosity level for logging to console. This can be useful while testing your integration with the Confidence SDK.
+
+_Note: the Confidence SDK has been intended to work as a single instance in your Application. Creating multiple instances in the same runtime could lead to unexpected behaviours._
+
+### Initialization strategy
+`confidence.fetchAndActivate()` is an async function that fetches the flags from the Confidence backend, stores the result on disk, and make the same data ready for the Application to be consumed.
+
+The alternative option is to call `confidence.activate()`: this loads previously fetched flags data from storage and makes that available for the Application to consume right away. To avoid waiting on backend calls when the Application starts, the suggested approach is to call `confidence.activate()` and then trigger a background refresh via `confidence.asyncFetch()` for future sessions.
 
 ### Setting the context
 The context is a key-value map that will be used for sampling and for targeting input in assigning feature flag values by the Confidence backend. It is also a crucial way to create dimensions for metrics generated by event data.
@@ -48,17 +66,7 @@ confidence.putContext("key", ConfidenceValue.String("value")) // this will mutat
 val otherConfidenceInstance = confidence.withContext("key", ConfidenceValue.String("value")) // this will return a new Confidence instance with the context changes applied but the context of the original instance is kept intact
 ```
 
-### Fetching and resolving flags
-Make the initial fetching of flags using the `activateAndFetch` method. This is a suspending function that will fetch the flags from the server and activate them.
-It needs to be run in a coroutine scope.
-
-```kotlin
-viewModelScope.launch {
-    confidence.fetchAndActivate()
-}
-```
-
-<!-- TODO: add more information about activate, fetchAndActivate and fetch methods. -->
+### Resolving flags
 
 **Once the flags are fetched and activated**, you can access their value using the `getValue` method or the `getFlag` method.
 Both methods uses generics to return a type defined by the default value type.