fix: Readme update

README.md

@@ -1,15 +1,15 @@
 # Swift Confidence SDK
 
-This repo contains the Swift [Confidence](https://confidence.spotify.com/) SDK to be used for accessing feature flags and for event tracking with Confidence.
+This repo contains the official Swift SDK for accessing feature flags and for event tracking with [Confidence](https://confidence.spotify.com/).
 
 It also contains the Confidence OpenFeature Provider, to be used in conjunction with the [OpenFeature SDK](https://openfeature.dev/docs/reference/concepts/provider).
 
-For documentation related to flags management and event tracking in Confidence, refer to the [Confidence documentation portal](https://confidence.spotify.com/platform/flags).
+For documentation related to flags management and event tracking in Confidence, refer to the [Confidence documentation 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 (in the backend) about which flags have been accessed by the application
+- Automatic data collection about which flags have been accessed by the application
 - Event tracking for instrumenting your application
 
 ## Dependency Setup
@@ -40,41 +40,50 @@ First, ensure you have your GitHub account added as an option (+ > Add Source Co
     * Clone locally using your preferred method
     * Use the "Add Local..." button to select the local folder
 
-**Note:** Option 2 is only recommended if you are making changes to the provider, you will also need to add
+**Note:** Option 2 is only recommended if you are making changes to the SDK. If working with the OpenFeature Provider, you will also need to add
 the relevant OpenFeature SDK dependency manually.
 
 ### Creating the Confidence instance
 
-You can create the Confidence instance using a Builder pattern.
-The `client secret` for your application is obtained in the Confidence portal [link](https://confidence.spotify.com/platform/flags/resolve-flags#creating-a-flag-client).
-
-Make the initial fetching of flags using the `activateAndFetch` method. This is an async function that will fetch the flags from the server and activate them.
-It needs to be run with `await`.
 ```swift
 import Confidence
 
 let confidence = Confidence.Builder(clientSecret: "mysecret").build()
 await confidence.fetchAndActivate()
 ```
 
-<!-- TODO: add more information about activate, fetchAndActivate and fetch methods. -->
+The client secret for your application can be generated in the Confidence portal.
 
-### 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.
+_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
 
-The Confidence SDK supports multiple ways to set the Context. Some of them are mutating the current context of the Confidence instance, others are returning a new instance with the context changes applied.
+`confidence.activateAndFetch()` is an async function that fetches the flags from the Confidence backend,
+stores the result on disk, and make the same data ready for theApplication 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 used for sampling and for targeting, when flag are evaluated by the Confidence backend.
+It is also appended to the tracked events, making it a great way to create dimensions for metrics in Confidence.
 
 ```swift
 confidence.putContext(context: ["key": ConfidenceValue(string: "value")]) // this will mutate the context of the current Confidence instance
-
-let 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
 ```
 
+Note that a `ConfidenceValue` is accepted a map values, which has a constructor for all the value types
+supported by Confidence.
+
 ### Resolving feature flags
-**Once the flags are fetched and activated**, you can access their value using the `getValue` method or the `getEvaluation` method.
-Both methods uses generics to return a type defined by the default value type.
+Once the flags are **activated**, you can access their value using the `getValue` method or the `getEvaluation` method.
+Both methods use generics to return a type defined by the default value type.
 
-The method `getEvaluation` returns an `Evaluation` object that contains the `value` of the flag, the `reason` for the value returned, and the `variant` selected.
+The method `getEvaluation` returns an `Evaluation` object that contains the `value` of the flag, the `reason`
+for the value returned, and the `variant` selected.
 
 
 The method `getValue` will simply return the assigned value or the default.
@@ -99,18 +108,10 @@ The SDK takes care of storing events in case of offline and retries in case of t
 Note that the data struct can't contain the key `context`, as that is reserved for entries set via `putContext` (see below):
 violating this rule will cause the track function to throw an error.
 
-To set context data to be appended to all tracked events:
+To set context data to be appended to all tracked events, here as example:
 ```swift
 confidence.putContext(context: ["os_version": ConfidenceValue(string: "17.0")])
-``` 
-
-Confidence APIs allows to spawn child instances that inherit the parent's context:
-```swift
-let child_confidence = confidence.withContext(["new_context", ConfidenceValue(string: "new_value")])
 ```
-Tracking events with `child_confidence` will include the context data from all its ancestors (i.e. `os_version`, and the evaluation context).
-
-Note: the context in the Confidence instance used to initialize the OpenFeature Provider is also part of the Evaluation Context used for flags.
 
 # OpenFeature Provider
 If you want to use OpenFeature, an OpenFeature Provider for the [OpenFeature SDK](https://github.com/open-feature/kotlin-swift) is also available.