Swift OpenFeature provider

The Unleash OpenFeature Swift provider lets Swift applications evaluate Unleash feature flags through the OpenFeature API.

The provider wraps the Unleash iOS SDK and uses the same frontend SDK behavior for fetching evaluated flags, polling, and metrics. Because the iOS SDK is a frontend SDK, this is a static-context provider: you set the evaluation context once on the OpenFeature API instead of passing it per evaluation, and context changes trigger a refetch of the flag configuration from Unleash.

Requirements

• iOS 15, macOS 12, tvOS 15, or watchOS 8 or later
• Swift 6.0 or later

Installation

Add the provider package with Swift Package Manager. The package depends on the OpenFeature Swift SDK and the Unleash iOS SDK, so you don’t need to add them separately.

1
dependencies: [
2
    .package(url: "https://github.com/Unleash/unleash-openfeature-swift-provider", from: "0.1.0"),
3
]

In Xcode, select File > Add Package Dependencies and enter the repository URL.

Configuration

Create an UnleashProvider with an UnleashProviderConfig, then register it with OpenFeature. The provider builds and owns the Unleash client. Connect to the Frontend API or Unleash Edge with a frontend token.

1
import OpenFeature
2
import UnleashOpenFeatureSwiftProvider
3
4
let provider = try UnleashProvider(config: UnleashProviderConfig(
5
    unleashUrl: "<YOUR_UNLEASH_URL>/api/frontend",
6
    clientKey: "<YOUR_FRONTEND_API_TOKEN>",
7
    appName: "my-ios-app"
8
))
9
10
await OpenFeatureAPI.shared.setProviderAndWait(
11
    provider: provider,
12
    initialContext: ImmutableContext(targetingKey: "user-123")
13
)

setProviderAndWait starts the Unleash client, fetches the flag configuration for the initial context, and waits for the fetch to complete before the provider is registered for use. After startup, the SDK continues polling for flag updates in the background.

The configuration also accepts the refreshInterval, metricsInterval, disableMetrics, environment, bootstrap, customHeaders, and pollerSession options, which behave like the corresponding Unleash iOS SDK options. Setting refreshInterval to 0 disables polling after the initial fetch.

Evaluate a flag

Build an OpenFeature client and evaluate flags through the OpenFeature API:

1
let client = OpenFeatureAPI.shared.getClient()
2
3
let enabled = client.getBooleanValue(key: "my-feature", defaultValue: false)

The provider supports all OpenFeature evaluation methods. Boolean evaluation uses the flag’s enabled state and returns false if the flag doesn’t exist, regardless of the default value you supply. All other types resolve from the payload of the flag’s variant:

• String values accept string and csv payloads.
• Integer and double values accept number payloads.
• Object values accept json payloads.

A missing flag, a disabled variant, or a variant without a payload returns the default value. A payload of the wrong type returns the default value with a type mismatch error, and a payload that can’t be parsed returns the default value with a parse error.

The detail methods, such as getStringDetails, also report the assigned variant name when the variant payload resolves successfully. The exception is boolean results, which never include a variant name because boolean evaluation only checks whether the flag is enabled. The evaluation reason is always UNKNOWN because Unleash SDKs don’t report why a flag evaluated the way it did.

Update the evaluation context

The provider ignores the per-evaluation context parameter. To change the context, update it on the OpenFeature API; the Unleash client then refetches the flag configuration for the new context:

1
await OpenFeatureAPI.shared.setEvaluationContextAndWait(
2
    evaluationContext: ImmutableContext(
3
        targetingKey: "user-456",
4
        structure: ImmutableStructure(attributes: ["plan": .string("pro")])
5
    )
6
)

Context mapping

The provider maps the OpenFeature evaluation context to an Unleash context.

If you set a targeting key, the provider maps it to userId. The targeting key takes precedence over a userId attribute set on the evaluation context. Attributes named after top-level Unleash context fields, such as sessionId and remoteAddress, map to those fields.

The provider adds all other scalar attributes, such as strings, numbers, booleans, and date values, to the Unleash context properties as strings; dates use ISO 8601 format. It discards list and structure attributes. The appName and environment fields come from the provider configuration and can’t be set through the evaluation context.

Shutdown

The OpenFeature Swift SDK has no provider shutdown hook, so stop the Unleash client explicitly when you no longer need the provider:

1
provider.onClose()
2
OpenFeatureAPI.shared.clearProvider()

onClose stops flag polling and metrics reporting and is idempotent. The provider doesn’t support re-initialization after shutdown; create a new provider instead.

Provider events

The provider doesn’t define events of its own. The OpenFeature Swift SDK emits the provider lifecycle events, such as ready, error, reconciling, and contextChanged, around initialization and context changes.

Example

To try the provider against your Unleash instance, clone the provider repository and run the boolean flag example with your Frontend API URL and token:

$
swift run boolean-flag-example \
>
  --url '<YOUR_UNLEASH_URL>/api/frontend' \
>
  --api-key "$UNLEASH_FRONTEND_TOKEN" \
>
  --flag-key my-feature \
>
  --targeting-key user-123