OpenFeature iOS SDK

OpenFeature 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.

🚀 Quick start

Requirements

• The minimum iOS version supported is: iOS 14.

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.).

Install

Xcode Dependencies

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.

1. Add as a remote repository
   • Search for [email protected]:open-feature/swift-sdk.git and click "Add Package"
2. 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 client SDK.

Swift Package Manager

If you manage dependencies through SPM, in the dependencies section of Package.swift add:

.package(url: "[email protected]:open-feature/swift-sdk.git", from: "0.2.1")

and in the target dependencies section add:

.product(name: "OpenFeature", package: "swift-sdk"),

Usage

import OpenFeature

Task {
    let provider = CustomProvider()
    // configure a provider, wait for it to complete its initialization tasks
    await OpenFeatureAPI.shared.setProviderAndWait(provider: provider)

    // get a bool flag value
    let client = OpenFeatureAPI.shared.getClient()
    let flagValue = client.getBooleanValue(key: "boolFlag", defaultValue: false)
}

🌟 Features

Status	Features	Description
✅	Providers	Integrate with a commercial, open source, or in-house feature management tool.
✅	Targeting	Contextually-aware flag evaluation using evaluation context.
✅	Hooks	Add functionality to various stages of the flag evaluation life-cycle.
❌	Logging	Integrate with popular logging packages.
❌	Named clients	Utilize multiple providers in a single application.
✅	Eventing	React to state changes in the provider or flag management system.
❌	Shutdown	Gracefully clean up a provider during application shutdown.
✅	Extending	Extend OpenFeature with custom providers and hooks.

_{Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌}

Providers

Providers are an abstraction between a flag management system and the OpenFeature SDK. Look here for a complete list of available providers. If the provider you're looking for hasn't been created yet, see the develop a provider section to learn how to build it yourself.

Once you've added a provider as a dependency, it can be registered with OpenFeature like this:

await OpenFeatureAPI.shared.setProviderAndWait(provider: MyProvider())

Asynchronous API that doesn't wait is also available

Targeting

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. In OpenFeature, we refer to this as targeting. If the flag management system you're using supports targeting, you can provide the input data using the evaluation context.

// Configure your evaluation context and pass it to OpenFeatureAPI
let ctx = MutableContext(
    targetingKey: userId,
    structure: MutableStructure(attributes: ["product": Value.string(productId)]))
OpenFeatureAPI.shared.setEvaluationContext(evaluationContext: ctx)

Hooks

Hooks allow for custom logic to be added at well-defined points of the flag evaluation life-cycle. Look here for a complete list of available hooks. If the hook you're looking for hasn't been created yet, see the develop a hook section to learn how to build it yourself.

Once you've added a hook as a dependency, it can be registered at the global, client, or flag invocation level.

// add a hook globally, to run on all evaluations
OpenFeatureAPI.shared.addHooks(hooks: ExampleHook())

// add a hook on this client, to run on all evaluations made by this client
val client = OpenFeatureAPI.shared.getClient()
client.addHooks(ExampleHook())

// add a hook for this evaluation only
_ = client.getValue(
    key: "key",
    defaultValue: false,
    options: FlagEvaluationOptions(hooks: [ExampleHook()]))

Logging

Logging customization is not yet available in the iOS SDK.

Named clients

Support for named clients is not yet available in the iOS SDK.

Eventing

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. Initialization events (PROVIDER_READY on success, PROVIDER_ERROR on failure) are dispatched for every provider. Some providers support additional events, such as PROVIDER_CONFIGURATION_CHANGED.

Please refer to the documentation of the provider you're using to see what events are supported.

let cancellable = OpenFeatureAPI.shared.observe().sink { event in
    switch event {
    case ProviderEvent.ready:
        // ...
    default:
        // ...
    }
}

Shutdown

A shutdown function is not yet available in the iOS SDK.

Extending

Develop a provider

To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency. You’ll then need to write the provider by implementing the FeatureProvider interface exported by the OpenFeature SDK.

import OpenFeature

final class CustomProvider: FeatureProvider {
    var hooks: [any Hook] = []
    var metadata: ProviderMetadata = CustomMetadata()

    func initialize(initialContext: EvaluationContext?) async {
        // add context-aware provider initialisation
    }

    func onContextSet(oldContext: EvaluationContext?, newContext: EvaluationContext) async {
        // add necessary changes on context change
    }

    func getBooleanEvaluation(
        key: String,
        defaultValue: Bool,
        context: EvaluationContext?
    ) throws -> ProviderEvaluation<Bool> {
        // resolve a boolean flag value
    }

    ...
}

Built a new provider? Let us know so we can add it to the docs!

Develop a hook

To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency. Implement your own hook by conforming to the Hook interface. To satisfy the interface, all methods (Before/After/Finally/Error) need to be defined.

class BooleanHook: Hook {
    typealias HookValue = Bool

    func before<HookValue>(ctx: HookContext<HookValue>, hints: [String: Any]) {
        // do something
    }

    func after<HookValue>(ctx: HookContext<HookValue>, details: FlagEvaluationDetails<HookValue>, hints: [String: Any]) {
        // do something
    }

    func error<HookValue>(ctx: HookContext<HookValue>, error: Error, hints: [String: Any]) {
        // do something
    }

    func finallyAfter<HookValue>(ctx: HookContext<HookValue>, hints: [String: Any]) {
        // do something
    }
}

Built a new hook? Let us know so we can add it to the docs!

⭐️ Support the project

• Give this repo a ⭐️!
• Follow us on social media:
  • Twitter: @openfeature
  • LinkedIn: OpenFeature
• Join us on Slack
• For more, check out our community page

🤝 Contributing

Interested in contributing? Great, we'd love your help! To get started, take a look at the CONTRIBUTING guide.

Thanks to everyone who has already contributed

Made with contrib.rocks.