> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpanel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Implement Feature Flags (Swift)

## Overview

This developer guide will assist you in configuring your iOS/macOS platform for Feature Flags using the [Mixpanel Swift SDK](/docs/tracking-methods/sdks/swift). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

For complete Swift SDK documentation, see the [Swift SDK guide](/docs/tracking-methods/sdks/swift).

## Prerequisites

Before implementing Feature Flags, ensure:

* You are on an Enterprise subscription plan and have the latest version of the SDK installed (minimum supported version is [`v5.1.3`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v5.1.3)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Initialization

Initializing the SDK with feature flags enabled requires passing a `FeatureFlagOptions` configuration to `MixpanelOptions`. This enables making an outbound request to Mixpanel servers with the current user context.
The server will assign the user context to a variant for each feature flag according to how they are configured in the Mixpanel UX.

The response will include an assigned variant for each flag that the user context is in a rollout group for. If a flag is not returned, it most likely signifies that the user was either not in the rollout percentage for a flag or in the configured targeting cohort.

**Example Usage**

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true)
))
```

If your flag is configured with a Variant Assignment Key other than `distinct_id` or `device_id` for any of the feature flags in your project, then the call to initialize feature flags must include those keys.

For example, for a Variant Assignment Key, `company_id`, you would setup the SDK as follows:

```swift theme={"system"}
let options = MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true, context: [
        "company_id": "X"
    ])
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)
```

If you are using Runtime Targeting in any of the feature flags in your project, then any properties that you use in targeting should be included in a `custom_properties` node within the context:

```swift theme={"system"}
let options = MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true, context: [
        "company_id": "X",
        "custom_properties": [
            "platform": "ios"
        ]
    ])
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)
```

## Flag Persistence

Minimum supported SDK version: [`v6.4.0`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v6.4.0)

By default (`networkOnly`), the SDK fetches fresh flag assignments and waits for the network response before variant calls complete. You can enable persistence to persist assignments to UserDefaults so they are available immediately on subsequent launches.

Configure a `variantLookupPolicy` on `FeatureFlagOptions`:

**`networkFirst`** — The SDK waits for the network on every launch. If the network call fails, the persisted value is returned as a fallback. Async getter calls block until the fetch completes (or the fallback is resolved).

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(
        enabled: true,
        variantLookupPolicy: .networkFirst()
    )
))

// getVariantValue waits for the network. Falls back to persisted value if network fails.
Mixpanel.mainInstance().flags.getVariantValue("my-feature-flag", fallbackValue: "control") { value in
    // value is from the network response, or from persistence if the network was unavailable
}
```

**`persistenceUntilNetworkSuccess`** — Persisted variants are returned immediately on launch. Each getter call while serving persisted data triggers a background network fetch (deduplicated — only one fetch runs at a time). If the fetch fails, persisted data continues to be served and the next getter call retries the fetch. Once a fetch succeeds, the in-memory state updates and subsequent calls no longer trigger background fetches.

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(
        enabled: true,
        variantLookupPolicy: .persistenceUntilNetworkSuccess()
    )
))

// getVariantValue returns immediately from persistence. Each call triggers a background fetch
// until a network response succeeds and replaces the persisted state.
Mixpanel.mainInstance().flags.getVariantValue("my-feature-flag", fallbackValue: "control") { value in
    // value is from persistence; background fetch retries on each call until network succeeds
}
```

To customize the TTL (default: 24 hours), pass a `TimeInterval`:

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(
        enabled: true,
        variantLookupPolicy: .networkFirst(persistenceTtl: 12 * 3600) // 12 hours
    )
))
```

### Variant source

Every `MixpanelFlagVariant` carries a `source` property indicating where the value came from: `.network`, `.persistence(persistedAt:)`, or `.fallback`. Use `getVariant()` to receive the full variant object.

```swift theme={"system"}
let fallback = MixpanelFlagVariant(key: "control", value: "control")
Mixpanel.mainInstance().flags.getVariant("my-feature-flag", fallback: fallback) { variant in
    let value = variant.value
    let source = variant.source // .network, .persistence(persistedAt:), or .fallback
}
```

### `$experiment_started` properties

When a variant is served, the `$experiment_started` exposure event includes:

* `$variant_source` — `"network"` or `"persistence"`
* `$persisted_at_in_ms` — epoch ms when the variant set was persisted *(persistence only)*
* `$ttl_in_ms` — the configured TTL in ms *(persistence only)*

<Note>
  Persisted variants are tied to the current `distinct_id`. Calling `identify()` with a new ID or calling `reset()` clears persisted data and triggers a fresh fetch.
</Note>

## Flag Reload

Following initialization, you can reload feature flag assignments in a couple of ways:

1. After a user logs in or out of your application and you call `identify`, a feature flag reload will be triggered.

```swift theme={"system"}
let updatedDistinctId = ""
Mixpanel.mainInstance().identify(distinctId: updatedDistinctId)
```

2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags.

```swift theme={"system"}
Mixpanel.mainInstance().flags.loadFlags()
```

3. To update the feature flags context after initialization and trigger a reload with the new values, use `setContext`. This completely replaces the previously set custom context.

```swift theme={"system"}
Mixpanel.mainInstance().flags.setContext([
    "company_id": "Y",
    "custom_properties": [
        "platform": "ios"
    ]
]) {
    // Flags have been re-fetched with the new context
}
```

4. Calling `reset()` clears all feature flag assignments from memory and triggers a new fetch for the updated `distinct_id`. Requires SDK version [`v6.4.0`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v6.4.0) or later.

```swift theme={"system"}
Mixpanel.mainInstance().reset()
// Flags are cleared immediately. A new fetch begins for the anonymous distinct_id.
```

## Deferred Flag Loading

By default, feature flags are automatically fetched when the app first enters the foreground (`prefetchFlags` defaults to `true`). If your workflow requires calling `identify()` before the first flag fetch — for example, to ensure flags are evaluated against the correct user — you can defer automatic loading by setting `prefetchFlags` to `false`:

```swift theme={"system"}
let options = MixpanelOptions(
    token: "YOUR_TOKEN",
    featureFlagOptions: FeatureFlagOptions(enabled: true, prefetchFlags: false)
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)

// Flags will not be fetched until identify() or loadFlags() is called
Mixpanel.mainInstance().identify(distinctId: "user-123")
```

When `prefetchFlags` is set to `false`, flags will not be loaded until you explicitly call `identify()` or `Mixpanel.mainInstance().flags.loadFlags()`.

## Flag Evaluation

Lookup the assigned value for a feature flag.
This action triggers tracking an exposure event, `$experiment_started` to your Mixpanel project.

### Asynchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```swift theme={"system"}
// Get just the flag value asynchronously
Mixpanel.mainInstance().flags.getVariantValue("my-feature-flag", fallbackValue: "control") { value in
    DispatchQueue.main.async {
        // Use flag value in your application logic
        if let stringValue = value as? String {
            switch stringValue {
            case "variant_a":
                showExperienceForVariantA()
            case "variant_b":
                showExperienceForVariantB()
            default:
                showDefaultExperience()
            }
        }
    }
}
```

**FeatureGates: Check if Flag is Enabled/Disabled**

```swift theme={"system"}
// Check if a boolean flag is enabled asynchronously
Mixpanel.mainInstance().flags.isEnabled("my-boolean-flag", fallbackValue: false) { isEnabled in
    DispatchQueue.main.async {
        if isEnabled {
            showNewFeature()
        } else {
            showOldFeature()
        }
    }
}
```

### Synchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```swift theme={"system"}
// Get just the flag value synchronously
let flagValue = Mixpanel.mainInstance().flags.getVariantValueSync("my-feature-flag", fallbackValue: "control")

// Use flag value in your application logic
if flagValue as? String == "variant_a" {
    showExperienceForVariantA()
} else if flagValue as? String == "variant_b" {
    showExperienceForVariantB()
} else {
    showDefaultExperience()
}
```

**Feature Gates: Check if Flag is Enabled/Disabled**

```swift theme={"system"}
// Check if a boolean flag is enabled
let isEnabled = Mixpanel.mainInstance().flags.isEnabledSync("my-boolean-flag", fallbackValue: false)

if isEnabled {
    showNewFeature()
} else {
    showOldFeature()
}
```

### Get All Flag Assignments

You can retrieve all feature flag assignments at once. These methods do **not** trigger `$experiment_started` tracking events.

**Synchronous**

`getAllVariantsSync()` returns a `[String: MixpanelFlagVariant]` dictionary containing all current flag assignments. If flags have not been loaded yet, it returns an empty dictionary.

```swift theme={"system"}
let allFlags = Mixpanel.mainInstance().flags.getAllVariantsSync()

for (flagName, variant) in allFlags {
    print("\(flagName): \(variant.value)")
}
```

**Asynchronous**

`getAllVariants(completion:)` returns a `[String: MixpanelFlagVariant]` dictionary via a completion handler. If flags have not been loaded yet, it will attempt to fetch them before returning.

```swift theme={"system"}
Mixpanel.mainInstance().flags.getAllVariants { allFlags in
    for (flagName, variant) in allFlags {
        print("\(flagName): \(variant.value)")
    }
}
```

## Frequently Asked Questions

### What if I'm not receiving any flags on SDK initialization?

1. **Check your project token**:

* Ensure you're using the correct project token from your [Mixpanel project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

2. **Review flag configuration**:

* Make sure your feature flag is enabled
* Check the flag's rollout percentage
  * User contexts that are not assigned to the rollout percentage will not receive flags
* If you are using a targeting cohort, verify on the mixpanel 'Users' page that the user's `distinct_id` is a member of that cohort.

3. **Review SDK parameters**:

* Ensure `FeatureFlagOptions(enabled: true)` is passed to `MixpanelOptions` via the `featureFlagOptions` parameter
* If using a custom Variant Assignment Key, ensure it is included in the `FeatureFlagOptions` `context` parameter
* If using Runtime Targeting, ensure all properties used in targeting are included in the `custom_properties` object within the `FeatureFlagOptions` context

4. **Check flags readiness**: Use `areFlagsReady()` to check if flags have been loaded before making synchronous calls
5. **Enable debug mode**: Set up logging to see detailed information about flag requests and responses