You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[OpenFeature][openfeature-website] is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool or in-house solution.
21
41
22
-
Standardizing feature flags unifies tools and vendors behind a common interface which avoids vendor lock-in at the code level. Additionally, it offers a framework for building extensions and integrations and allows providers to focus on their unique value proposition.
42
+
<!-- x-hide-in-docs-end -->
43
+
## 🚀 Quick start
23
44
24
-
##🔍 Requirements
45
+
###Requirements
25
46
26
47
- The minimum iOS version supported is: `iOS 14`.
27
48
28
49
Note that this library is intended to be used in a mobile context, and has not been evaluated for use in other type of applications (e.g. server applications, macOS, tvOS, watchOS, etc.).
29
50
30
-
##📦 Installation
51
+
### Install
31
52
32
-
### Xcode Dependencies
53
+
####Xcode Dependencies
33
54
34
55
You have two options, both start from File > Add Packages... in the code menu.
35
56
@@ -43,7 +64,7 @@ First, ensure you have your GitHub account added as an option (+ > Add Source Co
43
64
44
65
**Note:** Option 2 is only recommended if you are making changes to the client SDK.
45
66
46
-
### Swift Package Manager
67
+
####Swift Package Manager
47
68
48
69
If you manage dependencies through SPM, in the dependencies section of Package.swift add:
49
70
@@ -58,14 +79,7 @@ and in the target dependencies section add:
@@ -85,24 +99,105 @@ let client = OpenFeatureAPI.shared.getClient()
85
99
let flagValue = client.getBooleanValue(key: "boolFlag", defaultValue: false)
86
100
```
87
101
88
-
Setting a new provider or setting a new evaluation context are synchronous operations. The provider might execute I/O operations as part of these method calls (e.g. fetching flag evaluations from the backend and store them in a local cache). It's advised to not interact with the OpenFeature client until the relevant event has been emitted (see events below).
102
+
Setting a new provider or setting a new evaluation context might trigger asynchronous operations (e.g. fetching flag evaluations from the backend and store them in a local cache). It's advised to not interact with the OpenFeature client until the `ProviderReady` event has been emitted (see [Eventing](#eventing) below).
| ✅ |[Providers](#providers)| Integrate with a commercial, open source, or in-house feature management tool. |
110
+
| ✅ |[Targeting](#targeting)| Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |
111
+
| ✅ |[Hooks](#hooks)| Add functionality to various stages of the flag evaluation life-cycle. |
112
+
| ❌ |[Logging](#logging)| Integrate with popular logging packages. |
113
+
| ❌ |[Named clients](#named-clients)| Utilize multiple providers in a single application. |
114
+
| ✅ |[Eventing](#eventing)| React to state changes in the provider or flag management system. |
115
+
| ✅ |[Shutdown](#shutdown)| Gracefully clean up a provider during application shutdown. |
116
+
| ❌ |[Extending](#extending)| Extend OpenFeature with custom providers and hooks. |
117
+
118
+
<sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
119
+
120
+
### Providers
121
+
122
+
[Providers](https://openfeature.dev/docs/reference/concepts/provider) are an abstraction between a flag management system and the OpenFeature SDK.
123
+
Look [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Swift) for a complete list of available providers.
124
+
If the provider you're looking for hasn't been created yet, see the [develop a provider](#develop-a-provider) section to learn how to build it yourself.
125
+
126
+
Once you've added a provider as a dependency, it can be registered with OpenFeature like this:
Sometimes, the value of a flag must consider some dynamic criteria about the application or user, such as the user's location, IP, email address, or the server's location.
135
+
In OpenFeature, we refer to this as [targeting](https://openfeature.dev/specification/glossary#targeting).
136
+
If the flag management system you're using supports targeting, you can provide the input data using the [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).
137
+
138
+
```swift
139
+
// Configure your evaluation context and pass it to OpenFeatureAPI
[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.
149
+
Look [here](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Swift) for a complete list of available hooks.
150
+
If the hook you're looking for hasn't been created yet, see the [develop a hook](#develop-a-hook) section to learn how to build it yourself.
89
151
90
-
Please refer to our [documentation on static-context APIs](https://github.com/open-feature/spec/pull/171) for further information on how these APIs are structured for the use-case of mobile clients.
152
+
Once you've added a hook as a dependency, it can be registered at the global, client, or flag invocation level.
Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.
95
-
Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are emitted for every provider.
172
+
Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.
96
173
Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.
97
-
Please refer to the documentation of the provider you're using to see what events are supported and when they are emitted.
98
174
99
-
To register a handler for API level provider events, use the `OpenFeatureAPI``addHandler(observer:selector:event:)` function. Event handlers can also be removed using the equivalent `removeHandler` function. `Client`s also provide add and remove functions for listening to that specific client. A `ProviderEvent` enum is defined to ease subscription.
175
+
Please refer to the documentation of the provider you're using to see what events are supported.
100
176
101
-
Events can contain extra information in the `userInfo` dictionary of the notification. All events will contain a reference to the provider that emitted the event (under the `providerEventDetailsKeyProvider` key). Error events will also provide a reference to the underlying error (under the `providerEventDetailsKeyError` key). Finally, client specific events will contain a reference to the client (under the `providerEventDetailsKeyClient` key)
The OpenFeature API provides a close function to perform a cleanup of all registered providers.
190
+
This should only be called when your application is in the process of shutting down.
191
+
192
+
<!-- TODO: code example for global shutdown -->
104
193
105
-
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency. This can be a new repository or included in the existing contrib repository available under the OpenFeature organization. Finally, you’ll then need to write the provider itself. This can be accomplished by implementing the `FeatureProvider` protocol exported by the OpenFeature SDK.
194
+
## Extending
195
+
196
+
### Develop a provider
197
+
198
+
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
199
+
This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/swift-sdk-contrib) available under the OpenFeature organization.
200
+
You’ll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.
106
201
107
202
```swift
108
203
importOpenFeature
@@ -127,64 +222,63 @@ final class CustomProvider: FeatureProvider {
127
222
// resolve a boolean flag value
128
223
}
129
224
130
-
funcgetStringEvaluation(
131
-
key: String,
132
-
defaultValue: String,
133
-
context: EvaluationContext?
134
-
) throws-> ProviderEvaluation<String> {
135
-
// resolve a string flag value
225
+
...
226
+
}
227
+
228
+
```
229
+
> Built a new provider? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=provider&projects=&template=document-provider.yaml&title=%5BProvider%5D%3A+) so we can add it to the docs!
230
+
231
+
### Develop a hook
232
+
233
+
To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.
234
+
This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/swift-sdk-contrib) available under the OpenFeature organization.
235
+
Implement your own hook by conforming to the `Hook interface`.
236
+
To satisfy the interface, all methods (`Before`/`After`/`Finally`/`Error`) need to be defined.
237
+
To avoid defining empty functions, make use of the `UnimplementedHook` struct (which already implements all the empty functions).
> Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs!
0 commit comments