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
33
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.
34
+
<!-- x-hide-in-docs-end -->
35
+
## 🚀 Quick start
23
36
24
-
##🔍 Requirements
37
+
###Requirements
25
38
26
39
- The minimum iOS version supported is: `iOS 14`.
27
40
28
41
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
42
30
-
##📦 Installation
43
+
### Install
31
44
32
-
### Xcode Dependencies
45
+
####Xcode Dependencies
33
46
34
47
You have two options, both start from File > Add Packages... in the code menu.
35
48
@@ -43,7 +56,7 @@ First, ensure you have your GitHub account added as an option (+ > Add Source Co
43
56
44
57
**Note:** Option 2 is only recommended if you are making changes to the client SDK.
45
58
46
-
### Swift Package Manager
59
+
####Swift Package Manager
47
60
48
61
If you manage dependencies through SPM, in the dependencies section of Package.swift add:
49
62
@@ -58,14 +71,7 @@ and in the target dependencies section add:
@@ -85,24 +91,97 @@ let client = OpenFeatureAPI.shared.getClient()
85
91
let flagValue = client.getBooleanValue(key: "boolFlag", defaultValue: false)
86
92
```
87
93
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).
94
+
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. |
102
+
| ✅ |[Targeting](#targeting)| Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |
103
+
| ✅ |[Hooks](#hooks)| Add functionality to various stages of the flag evaluation life-cycle. |
104
+
| ❌ |[Logging](#logging)| Integrate with popular logging packages. |
105
+
| ❌ |[Named clients](#named-clients)| Utilize multiple providers in a single application. |
106
+
| ✅ |[Eventing](#eventing)| React to state changes in the provider or flag management system. |
107
+
| ❌ |[Shutdown](#shutdown)| Gracefully clean up a provider during application shutdown. |
108
+
| ✅ |[Extending](#extending)| Extend OpenFeature with custom providers and hooks. |
109
+
110
+
<sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
111
+
112
+
### Providers
113
+
114
+
[Providers](https://openfeature.dev/docs/reference/concepts/provider) are an abstraction between a flag management system and the OpenFeature SDK.
115
+
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.
116
+
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.
117
+
118
+
Once you've added a provider as a dependency, it can be registered with OpenFeature like this:
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.
126
+
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.
127
+
In OpenFeature, we refer to this as [targeting](https://openfeature.dev/specification/glossary#targeting).
128
+
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).
91
129
92
-
### Events
130
+
```swift
131
+
// 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.
141
+
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.
142
+
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.
143
+
144
+
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.
164
+
Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.
96
165
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
166
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.
167
+
Please refer to the documentation of the provider you're using to see what events are supported.
100
168
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)
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.
183
+
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
184
+
You’ll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.
106
185
107
186
```swift
108
187
importOpenFeature
@@ -127,64 +206,61 @@ final class CustomProvider: FeatureProvider {
127
206
// resolve a boolean flag value
128
207
}
129
208
130
-
funcgetStringEvaluation(
131
-
key: String,
132
-
defaultValue: String,
133
-
context: EvaluationContext?
134
-
) throws-> ProviderEvaluation<String> {
135
-
// resolve a string flag value
209
+
...
210
+
}
211
+
212
+
```
213
+
> 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!
214
+
215
+
### Develop a hook
216
+
217
+
To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.
218
+
Implement your own hook by conforming to the `Hook interface`.
219
+
To satisfy the interface, all methods (`Before`/`After`/`Finally`/`Error`) need to be defined.
> 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