iOS SDK
The Unleash iOS SDK is a Swift client that lets you evaluate feature flags in iOS and macOS applications. It connects to Unleash or Unleash Edge to fetch evaluated flags for a given Unleash context.
You can use this SDK with Unleash Enterprise or Unleash Open Source.
For an overview of how Unleash SDKs work, including offline behavior, feature compatibility across SDKs, and default refresh and metrics intervals, refer to the SDK overview.
Requirements
- MacOS: 12.15
- iOS: 12
Usage
To get started, import the SDK and initialize the Unleash client:
iOS >= 13
iOS >= 12
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 to0to only poll once and disable a periodic polling [Int]appName: The application name identifier [String]context: Initial Unleash context fields (likeuserId,sessionId, etc.), excludingappNameandenvironmentwhich 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).
ready event), checking a feature flag might return the default value (often false). To ensure the configuration is loaded before checking flags, subscribe to the ready event. See the Events section for details.Once the configuration is loaded, you can check if a feature flag is enabled:
You can also set up variants:
Configuration options
The Unleash SDK accepts the following initialization options:
Bootstrap
You can bootstrap the SDK with flag configuration to evaluate flags before connecting to Unleash. Provide the bootstrap as a list of Toggle objects or from a JSON file matching the Frontend API response format.
Inline data
JSON file
You can inject the bootstrap at initialization or when calling start:
- If you initialize the client with a
Poller, inject the bootstrap directly into the poller. Any bootstrap data injected into the 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:
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:
Custom PollerSession
If you want to use a custom URLSession or intercept URLRequest you can provide a custom PollerSession to the client.
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-TypeIf-None-Match- anything starting with
unleash-(unleash-appname,unleash-connection-id,unleash-sdk, …)
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.
Events
The client emits events that you can subscribe to using the subscribe(name:callback:) method or the UnleashEvent enum.
The client emits the following 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.impression(UnleashEvent.impression): Emitted whenisEnabled(name:)orgetVariant(name:)is called for a flag with impression data enabled.
Subscribe using the subscribe(name:callback:) method or the UnleashEvent enum:
Impression events
To track feature exposures, enable impression data for the flags you want to track, then subscribe to the impression event:
Installation
In your Xcode project, go to File -> Swift Packages -> Add Package Dependency, supply the link to this repository, and set the appropriate package constraints (typically up to next major version).
Migrating to v2
In v2, the StorageProvider interface was changed to accept all flags at once:
If you have a custom StorageProvider implementation, you’ll need to update it.