This repo contains the Swift Confidence SDK to be used for accessing feature flags and for event tracking with Confidence.
It also contains the Confidence OpenFeature Provider, to be used in conjunction with the OpenFeature SDK.
For documentation related to flags management and event tracking in Confidence, refer to the Confidence documentation portal.
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
- Event tracking for instrumenting your application
In the dependencies section of Package.swift add:
.package(url: "git@github.com:spotify/confidence-sdk-swift.git", from: "0.2.1")
and in the target dependencies section add:
.product(name: "Confidence", package: "confidence-sdk-swift"),
You have two options, both start from File > Add Packages... in the code menu.
First, ensure you have your GitHub account added as an option (+ > Add Source Control Account...). You will need to create a Personal Access Token with the permissions defined in the Xcode interface.
- Add as a remote repository
- Search for
git@github.com:spotify/confidence-sdk-swift.git
and click "Add Package"
- Search for
- Clone the repository locally
- 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 the relevant OpenFeature SDK dependency manually.
You can create the Confidence instance using a Builder pattern.
The client secret
for your application is obtained in the Confidence portal link.
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
.
import Confidence
let confidence = Confidence.Builder(clientSecret: "mysecret").build()
await confidence.fetchAndActivate()
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.
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.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
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.
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.
In the case of an error, the default value will be returned and the Evaluation
contains information about the error.
let message: String = confidence.getValue(key: "flag-name.message", defaultValue: "default message")
let messageFlag: Evaluation<String> = try confidence.getEvaluation(key: "flag-name.message", defaultValue: "default message")
let messageValue = messageFlag.value
// message and messageValue are the same
The Confidence instance offers APIs to track events, which are uploaded to the Confidence backend:
try confidence.track(eventName: "MyEvent", data: ["field": ConfidenceValue(string("value"))])
The SDK takes care of storing events in case of offline and retries in case of transient failures.
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:
confidence.putContext(context: ["os_version": ConfidenceValue(string: "17.0")])
Confidence APIs allows to spawn child instances that inherit the parent's context:
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.
If you want to use OpenFeature, an OpenFeature Provider for the OpenFeature SDK is also available.
See the dedicated Provider Readme.