Skip to main content

Flagsmith iOS SDK

This library can be used with iOS and Mac applications. The source code for the client is available on GitHub.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate Flagsmith into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'FlagsmithClient', '~> 1.0'

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. You can use it to install Flagsmith by adding the description to your Package.swift file:

dependencies: [
.package(url: "https://github.com/Flagsmith/flagsmith-ios-client.git", from: "1.1.1"),
]

Basic Usage

The SDK is initialised against a single environment within a project on https://flagsmith.com, for example the Development or Production environment. You can find your Client-side Environment Key in the Environment settings page.

Initialization

Within your application delegate (usually AppDelegate.swift) add:

import FlagsmithClient
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

Flagsmith.shared.apiKey = "<YOUR_API_KEY>"
// The rest of your launch method code
}

Now you are all set to retrieve feature flags from your project. For example to list and print all flags:

Flagsmith.shared.getFeatureFlags() { (result) in
switch result {
case .success(let flags):
for flag in flags {
let name = flag.feature.name
let value = flag.value?.stringValue
let enabled = flag.enabled
print(name, "= enabled:", enabled, "value:", value ?? "nil")
}
case .failure(let error):
print(error)
}
}

Note that you can use:

  • flag.value?.stringValue
  • flag.value?.intValue

Based on your desired type.

To retrieve a feature flag boolean value by its name:

Flagsmith.shared.hasFeatureFlag(withID: "test_feature1", forIdentity: nil) { (result) in
print(result)
}

To retrieve a config value by its name:

Flagsmith.shared.getFeatureValue(withID: "test_feature2", forIdentity: nil) { (result) in
switch result {
case .success(let value):
print(value ?? "nil")
case .failure(let error):
print(error)
}
}

These methods can also specify a particular identity to retrieve the values for a user registration. See Identities , using the forIdentity parameter.

To retrieve a trait for a particular identity (see Traits):

Flagsmith.shared.getTraits(forIdentity: "test_user@test.com") {(result) in
switch result {
case .success(let traits):
for trait in traits {
let name = trait.key
let value = trait.value
print(name, "=", value)
}
case .failure(let error):
print(error)
}
}

To retrieve a flag for a particular identity:

Flagsmith.shared.getFeatureFlags(forIdentity: "test_user@test.com") {(result) in
switch result {
case .success(let flags):
for flag in flags {
let name = flag.feature.name
let value = flag.value?.stringValue
let enabled = flag.enabled
print(name, "= enabled:", enabled, "value:", value ?? "nil")
}
case .failure(let error):
print(error)
}
}

If you would prefer to do this using async/await you can do the following:

let flags = try await Flagsmith.shared.getFeatureFlags(forIdentity: "test_user@test.com")
for flag in flags {
let name = flag.feature.name
let value = flag.value?.stringValue
let enabled = flag.enabled
print(name, "= enabled:", enabled, "value:", value ?? "nil")
}

Override Default Configuration

In AppDelegate.swift:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Override point for customization after application launch.
Flagsmith.shared.apiKey = "<add your API key from the Flagsmith settings page>"

// set cache on / off (defaults to off)
Flagsmith.shared.cacheConfig.useCache = true

// set custom cache to use (defaults to shared URLCache)
//Flagsmith.shared.cacheConfig.cache = <CUSTOM_CACHE>

// set skip API on / off (defaults to off)
Flagsmith.shared.cacheConfig.skipAPI = false

// set cache TTL in seconds (defaults to 0, i.e. infinite)
Flagsmith.shared.cacheConfig.cacheTTL = 90

// set analytics on or off
Flagsmith.shared.enableAnalytics = true

// set the analytics flush period in seconds
Flagsmith.shared.analyticsFlushPeriod = 10

Flagsmith.shared.getFeatureFlags() { (result) in
print(result)
}
Flagsmith.shared.hasFeatureFlag(withID: "freeze_delinquent_accounts") { (result) in
print(result)
}
//Flagsmith.shared.setTrait(Trait(key: "<my_key>", value: "<my_value>"), forIdentity: "<my_identity>") { (result) in print(result) }
//Flagsmith.shared.getIdentity("<my_key>") { (result) in print(result) }
return true
}

Swift Concurrency

When running with Swift version 5.5.2 and greater (Xcode 13.2), async versions of the Flagsmith API become available. These are provided using the generic withCheckedThrowingContinuation(function:_:) Swift api, to wrap the closure based syntax. The async/await syntax provides a streamlined execution flow leading to greater code clarity. For example:

/// (Example) Setup the app based on the available feature flags.
func determineAppConfiguration() async throws {
let flagsmith = Flagsmith.shared

if try await flagsmith.hasFeatureFlag(withID: "ab_test_enabled") {
if let theme = try await flagsmith.getFeatureValue(withID: "app_theme") {
setTheme(theme)
} else {
let flags = try await flagsmith.getFeatureFlags()
processFlags(flags)
}
} else {
let trait = Trait(key: "selected_tint_color", value: "orange")
let identity = "4DDBFBCA-3B6E-4C59-B107-954F84FD7F6D"
try await flagsmith.setTrait(trait, forIdentity: identity)
}
}

Providing Default Flags

You can define default flag values when initialising the SDK. This ensures that your application works as intended in the event that it cannot receive a response from our API.

// set default flags
Flagsmith.shared.defaultFlags = [Flag(featureName: "feature_a", enabled: false),
Flag(featureName: "font_size", intValue:12, enabled: true),
Flag(featureName: "my_name", stringValue:"Testing", enabled: true)]

Cache

By default, the cache is off. When turned on, Flagsmith will cache all flags returned by the API (to permanent storage), and in case of a failed response, fall back on the cached values. The cache can be turned off or on using:

// set cache on / off (defaults to off)
Flagsmith.shared.cacheConfig.useCache = true

You can also set a TTL for the cache (in seconds), and request that Flagsmith skip calling the API if a valid cache is present

// set skip API on / off (defaults to off)
Flagsmith.shared.cacheConfig.skipAPI = false

// set cache TTL in seconds (defaults to 0, i.e. infinite)
Flagsmith.shared.cacheConfig.cacheTTL = 0

If more customisation is required, you can override the cache implemention with your own subclass of URLCache, using the following code.

// set custom cache to use (defaults to shared URLCache)
Flagsmith.shared.cacheConfig.cache = <CUSTOM_CACHE_IMPLEMENTATION>

Override default configuration

By default, the client uses a default configuration. You can override the configuration as follows:

Override just the default API URI with your own:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

Flagsmith.shared.apiKey = "<YOUR_API_KEY>"
Flagsmith.shared.baseURL = "https://<your-self-hosted-api>/api/v1/"
// The rest of your launch method code
}