iOS SDK

This client-side Swift SDK helps you integrate with Unleash and evaluate feature flags inside your application.

You can use this client with Unleash Enterprise or Unleash Open Source.

You can connect the SDK to Unleash in two ways:

• Directly to your Unleash instance using the Frontend API.
• Using Unleash Edge, a lightweight service acting as a caching and evaluation layer between the SDK and your main Unleash instance. Unleash Edge fetches flag configurations, caches them in-memory, and handles evaluation locally for faster responses and high availability.

In both setups, the SDK retrieves feature flag configurations for the provided context. The SDK caches the received flag configurations in memory and refreshes them periodically (at a configurable interval). This makes local evaluations like isEnabled() extremely fast.

Requirements

• MacOS: 12.15
• iOS: 12

Usage

To get started, import the SDK and initialize the Unleash client:

iOS >= 13

1
import SwiftUI
2
import UnleashProxyClientSwift
3
4
// Setup Unleash in the context where it makes most sense
5
6
var unleash = UnleashProxyClientSwift.UnleashClient(
7
    unleashUrl: "https://<unleash-instance>/api/frontend",
8
    clientKey: "<client-side-api-token>",
9
    refreshInterval: 15,
10
    appName: "test",
11
    context: ["userId": "c3b155b0-5ebe-4a20-8386-e0cab160051e"]
12
)
13
14
unleash.start()

iOS >= 12

1
import SwiftUI
2
import UnleashProxyClientSwift
3
4
// Setup Unleash in the context where it makes most sense
5
6
var unleash = UnleashProxyClientSwift.UnleashClientBase(
7
    unleashUrl: "https://<unleash-instance>/api/frontend",
8
    clientKey: "<client-side-api-token>",
9
    refreshInterval: 15,
10
    appName: "test",
11
    context: ["userId": "c3b155b0-5ebe-4a20-8386-e0cab160051e"]
12
)
13
14
unleash.start()

In the example above we import the UnleashProxyClientSwift and instantiate the client. You need to provide the following parameters:

• unleashUrl: The full URL to either the Unleash Frontend API or an Unleash Edge instance [String]
• clientKey: A frontend API token for authenticating with the Frontend API or Unleash Edge [String]
• refreshInterval: The polling interval in seconds, set to 0 to only poll once and disable a periodic polling [Int]
• appName: The application name identifier [String]
• context: Initial Unleash context fields (like userId, sessionId, etc.), excluding appName and environment which are configured separately. [String: String]

Calling unleash.start() makes the initial request to retrieve the feature flag configuration and starts the background polling interval (if refreshInterval > 0).

Once the configuration is loaded, you can check if a feature flag is enabled:

1
if unleash.isEnabled(name: "ios") {
2
    // do something
3
} else {
4
   // do something else
5
}

You can also set up variants:

1
var variant = unleash.getVariant(name: "ios")
2
if variant.enabled {
3
    // do something
4
} else {
5
   // do something else
6
}

Available Options

The Unleash SDK accepts the following initialization options:

Bootstrapping

You can provide the initial feature flag state to the Unleash client SDK. This is useful when you have a known initial state for your feature flag. This state can be bootstrapped to the client via a list of Toggle objects, or from a file matching a response from the Frontend API. For example:

Bootstrap From Hard-coded List

1
// Note variant and payload can be optional.
2
let bootstrapList = Bootstrap
3
    .toggles(
4
        [
5
            Toggle(name: "Foo", enabled: true),
6
            Toggle(
7
                name: "Bar",
8
                enabled: false,
9
                variant: Variant(
10
                    name: "bar",
11
                    enabled: true,
12
                    featureEnabled: true,
13
                    payload: Payload(type: "string", value: "baz")
14
                )
15
            )
16
        ]
17
    )

Bootstrap From File Matching Frontend API Response

1
{
2
  "toggles": [
3
      {
4
        "name": "no-variant",
5
        "enabled": true
6
      },
7
      {
8
        "name": "disabled-with-variant-disabled-no-payload",
9
        "enabled": false,
10
        "variant": {
11
            "name": "foo",
12
            "enabled": false,
13
            "feature_enabled": false
14
        }
15
      },
16
      {
17
        "name": "enabled-with-variant-enabled-and-payload",
18
        "enabled": true,
19
        "variant": {
20
            "name": "bar",
21
            "enabled": true,
22
            "feature_enabled": true,
23
            "payload": {
24
                "type": "string",
25
                "value": "baz"
26
            }
27
        }
28
      }
29
  ]
30
}

1
guard let filePath = Bundle.main.path(forResource: "FeatureResponseFile", ofType: "json") else {
2
    // Handle missing file
3
}
4
5
let bootstrapFile = Bootstrap.jsonFile(path: filePath)

Using the Bootstrap List of Toggles

Whether from a hard-coded list, or a json file, the bootstrap toggles can be injected into the Unleash Edge or Proxy client either at initialisation time, or when calling start. For example:

1
import SwiftUI
2
import UnleashProxyClientSwift
3
4
// Setup Unleash in the context where it makes most sense
5
6
let unleash = UnleashClient(
7
    unleashUrl: "https://<unleash-instance>/api/frontend",
8
    clientKey: "<client-side-api-token>",
9
    bootstrap: .toggles([Toggle(name: "Foo", enabled: true)])
10
)
11
12
// Toggles can be accessed now ahead of starting client
13
let isFooEnabled = unleash.isEnabled(name: "Foo") // true
14
15
// Or provide when starting in case of slow/faulty connection
16
unleash.start(bootstrap: .jsonFile("path/to/json/file"))
17
18
// Or using async-await concurrency (>= iOS13)
19
await unleash.start(bootstrap: .jsonFile("path/to/json/file"))

Important Notices

• If you initialise the Unleash Edge client with a Poller, inject the bootstrap directly into the poller. Any bootstrap data injected into the Unleash client options will be ignored when a custom poller is also provided.
• Bootstrapped flag configurations are replaced entirely after the first successful fetch.
• If bootstrap flags are provided when calling start, the first fetch occurs after the configured refreshInterval (default 15 seconds).
• Calling updateContext(...) before the first fetch removes any bootstrapped flags.

Update Context

To update the context, use the following method:

1
var context: [String: String] = [:]
2
context["userId"] = "c3b155b0-5ebe-4a20-8386-e0cab160051e"
3
unleash.updateContext(context: context)

This will stop and start the polling interval in order to renew polling with new context values.

You can use any of the predefined fields. If you need to support custom properties pass them as the second argument:

1
var context: [String: String] = [:]
2
context["userId"] = "c3b155b0-5ebe-4a20-8386-e0cab160051e"
3
var properties: [String: String] = [:]
4
properties["customKey"] = "customValue";
5
unleash.updateContext(context: context, properties: properties)

Custom PollerSession

If you want to use a custom URLSession or intercept URLRequest you can provide a custom PollerSession to the client.

1
class CustomPollerSession: PollerSession {
2
    func perform(_ request: URLRequest, completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) {
3
        // Custom URLSession configuration
4
        let configuration = URLSessionConfiguration.default
5
        configuration.timeoutIntervalForRequest = 30
6
7
        // Modify URLRequest if needed
8
        var modifiedRequest = request
9
        modifiedRequest.setValue("foo", forHTTPHeaderField: "bar")
10
11
        let session = URLSession(configuration: configuration)
12
        session.dataTask(with: modifiedRequest, completionHandler: completionHandler).resume()
13
    }
14
}
15
16
// Use when initializing Unleash client
17
var unleash = UnleashProxyClientSwift.UnleashClient(
18
    unleashUrl: unleashUrl,
19
    clientKey: clientKey,
20
    pollerSession: CustomPollerSession()
21
)

Custom HTTP Headers

If you want the client to send custom HTTP headers with all requests to the Unleash API you can define that by setting them via the UnleashClientBase.

Custom and dynamic custom headers does not apply to sensitive headers.

• Content-Type
• If-None-Match
• anything starting with unleash- (unleash-appname, unleash-connection-id, unleash-sdk, …)

1
var unleash = UnleashProxyClientSwift.UnleashClientBase(
2
    unleashUrl: unleashUrl,
3
    clientKey: clientKey,
4
    refreshInterval: 15,
5
    appName: "test",
6
    context: ["userId": "c3b155b0-5ebe-4a20-8386-e0cab160051e"],
7
    customHeaders: ["X-Custom-Header": "CustomValue", "X-Another-Header": "AnotherValue"]
8
)

Dynamic Custom HTTP Headers

If you need custom HTTP headers that change during the lifetime of the client, a provider can be defined via the UnleashClientBase.

1
public class MyCustomHeadersProvider: CustomHeadersProvider {
2
    public init() {}
3
    public func getCustomHeaders() -> [String: String] {
4
        let token = "Acquire or refresh token";
5
        return ["Authorization": token]
6
    }
7
}

1
let myCustomHeadersProvider: CustomHeadersProvider = MyCustomHeadersProvider()
2
3
var unleash = UnleashProxyClientSwift.UnleashClientBase(
4
        unleashUrl: unleashUrl,
5
        clientKey: clientKey,
6
        refreshInterval: 15,
7
        appName: "test",
8
        context: ["userId": "c3b155b0-5ebe-4a20-8386-e0cab160051e"],
9
        customHeadersProvider: myCustomHeadersProvider
10
)

Events

The client emits events that you can subscribe to using the subscribe(name:callback:) method or the UnleashEvent enum.

Standard Events

• ready (UnleashEvent.ready): Emitted once the client has successfully fetched and cached the initial feature flag configurations.
• update (UnleashEvent.update): Emitted when a subsequent fetch results in a change to the feature flag configurations.
• sent (UnleashEvent.sent): Emitted when usage metrics have been successfully sent to the server.
• error (UnleashEvent.error): Emitted if an error occurs when trying to send metrics.

Subscribing to Standard Events

1
func handleReady() {
2
    // do this when unleash is ready
3
}
4
5
unleash.subscribe(name: "ready", callback: handleReady)
6
7
func handleUpdate() {
8
    // do this when unleash is updated
9
}
10
11
unleash.subscribe(name: "update", callback: handleUpdate)

Alternatively you can use the enum UnleashEvent, for example:

1
unleash.subscribe(.ready, callback: handleUpdate)

Impression Data Events

This SDK allows you to subscribe to Impression Data events. These events provide granular, real-time tracking of feature exposures. You must specifically enable impression data for the feature flags you’d like to track.

When isEnabled(name:) or getVariant(name:) is called for a feature flag that has impression data enabled, the SDK creates an ImpressionEvent object that is broadcast internally using the event name impression (also accessible via the UnleashEvent.impression enum case).

Subscribing to Impression Data Events

1
import UnleashProxyClientSwift
2
3
// Define your handler that accepts the raw payload and casts to ImpressionEvent
4
func handleImpressionEvent(_ payload: Any?) {
5
    guard let impressionEvent = payload as? UnleashProxyClientSwift.ImpressionEvent else {
6
        // Optional: Log a warning if casting fails
7
        return
8
    }
9
10
    // Additional logic to send impression data to your analytics tool
11
}
12
13
// Subscribe to the impression event, providing the handler function
14
unleash.subscribe(.impression, callback: handleImpressionEvent)
15
16
// Or: unleash.subscribe(name: "impression", callback: handleImpressionEvent)

Releasing

Note: To release the package you’ll need to have CocoaPods installed.

Update Sources/Version/Version.swift with the new version number. This version is used in unleash-sdk header as a version reported to Unleash server.

Then, add a Git tag matching the version number. Releasing the tag is sufficient for the Swift package manager, but you might also want to ensure CocoaPods users can also consume the code.

1
git tag -a 0.0.4 -m "v0.0.4"

Please make sure that the tag is pushed to the remote.

The next few commands assume that you have CocoaPods installed and available on your shell.

First, validate your session with CocoaPods with the following command:

1
pod trunk register <email> "Your name"

The email that owns this package is the general Unleash team email. CocoaPods will send a link to this email, click it to validate your shell session.

Bump the version number of the package, you can find this in UnleashProxyClientSwift.podspec, we use SemVer for this project. Once that’s committed and merged to main:

Linting the podspec is always a good idea:

1
pod spec lint UnleashProxyClientSwift.podspec --use-libraries

Once that succeeds, you can do the actual release:

1
pod trunk push UnleashProxyClientSwift.podspec --allow-warnings --use-libraries

Testing

In order to test this package you can run the swift test command. To test thread safety, run swift test with:

swift test --sanitize=thread

This gives you warnings in the console when you have any data races.

Installation

Follow the following steps in order to install the unleash-ios-sdk:

1. In your Xcode project go to File -> Swift Packages -> Add Package Dependency
2. Supply the link to this repository
3. Set the appropriate package constraints (typically up to next major version)
4. Let Xcode find and install the necessary packages

Once you’re done, you should see SwiftEventBus and UnleashProxyClientSwift listed as dependencies in the file explorer of your project.

Upgrade Guide From 1.x -> 2.x

In 2.0.0 the StorageProvider public interface was changed to be more in line with other SDKs. Specifically the set method was changed to accept all flags at once. It now has the following interface:

func set(values: [String: Toggle])

If you are running with your own StorageProvider implementation you’ll need to make changes to your implementation.