Skip to content
Featureflip Docs

Swift Feature Flags Quickstart

This guide gets you from zero to evaluating a feature flag in a Swift application. The SDK is a client-side SDK — flags are evaluated server-side and only values are returned.

Prerequisites

Section titled “Prerequisites”
  • A Featureflip account with at least one feature flag created
  • A client SDK key from your environment settings
  • Flags you want to use must have Client-side visible enabled
  • Swift 5.9+, targeting iOS 15+ / macOS 13+ / tvOS 15+ / watchOS 8+

Install

Section titled “Install”

Add the package to your project via Swift Package Manager.

In Xcode: File → Add Package Dependencies, then enter the repository URL.

Or in Package.swift:

dependencies: [
    .package(url: "https://github.com/canopy-labs/featureflip-swift", from: "2.0.0")
]

Initialize the client

Section titled “Initialize the client”
import Featureflip


let config = FeatureflipConfig(
    clientKey: "your-client-sdk-key",
    context: ["user_id": "user-123"]
)


let client = FeatureflipClient(config: config)
await client.initialize()

initialize() fetches flag values from the evaluation API and starts SSE streaming for real-time updates. Cached values from disk are used while the network request is in flight.

Evaluate a flag

Section titled “Evaluate a flag”
let showBanner = client.boolVariation("new-banner", default: false)


if showBanner {
    print("Showing the new banner")
} else {
    print("Using the default experience")
}

The default parameter is returned when the flag is missing or has an unexpected type.

Other variation methods are available for different value types:

let color = client.stringVariation("banner-color", default: "blue")
let limit = client.numberVariation("rate-limit", default: 100.0)

Clean up

Section titled “Clean up”

Close the client when your app is shutting down:

await client.close()

The SDK automatically pauses streaming when the app enters the background and resumes on foreground.

How it works

Section titled “How it works”

The Swift SDK is a client-side SDK — flags are evaluated on the Featureflip server, not locally in your app. On initialization, the SDK sends the user context to the evaluation API and receives pre-evaluated flag values. It then opens an SSE (Server-Sent Events) connection that pushes updates in real-time whenever flags change in the dashboard.

Flag values are cached to disk, so your app has working values immediately on launch while the SDK fetches fresh data in the background. When the app moves to the background, the SDK pauses the SSE connection to conserve battery and resumes it when the app returns to the foreground.

Troubleshooting

Section titled “Troubleshooting”

initialize() hangs or returns unexpected values

Verify you are using a client SDK key (not a server SDK key). Client and server keys are different — using the wrong type results in authentication errors or empty responses. Also confirm that the flags you want to access have Client-side visible enabled in the dashboard.

Flag values do not update in real-time

The SDK uses SSE streaming for updates. If your app is behind a network that blocks long-lived connections (some corporate Wi-Fi or VPN configurations), updates may be delayed until the next polling cycle. Check your device’s network connectivity if updates seem stuck.

Xcode build errors after adding the package

Ensure your deployment target meets the minimum: iOS 15, macOS 13, tvOS 15, or watchOS 8. If Xcode shows “Missing package product” errors, try resetting the package cache: File → Packages → Reset Package Caches. Also verify you are using Swift 5.9+ in your project settings.

Next steps

Section titled “Next steps”