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. 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.

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). If not, please follow this doc to install the SDK.
• You have your Project Token from your Mixpanel Project Settings

Flag Initialization

Initializing the SDK with feature flags enabled requires setting the featureFlagsEnabled option to true. 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

Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagsEnabled: true
))

If your flag is configured with a Variant Assignment Key other than distinct_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:

let options = MixpanelOptions(
    featureFlagsEnabled: true,
    featureFlagsContext: [
        "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 customProperties node within the context:

let options = MixpanelOptions(
    featureFlagsEnabled: true,
    featureFlagsContext: [
        "company_id": "X",
        "customProperties": [
            "platform": "ios"
        ]
    ]
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)

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.

let updatedDistinctId = ""
Mixpanel.mainInstance().identify(distinctId: updatedDistinctId)

2. If variant assignment keys or properties used in Runtime Targeting change during the lifetime of your application, you can manually reload flags by updating the context:

Mixpanel.mainInstance().flags.delegate?.getOptions().featureFlagsContext = [
    "company_id": "Y",
    "customProperties": [
        "platform": "ios"
    ]
]
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

// 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":
                showExperimentForVariantA()
            case "variant_b":
                showExperimentForVariantB()
            default:
                showDefaultExperience()
            }
        }
    }
}

FeatureGates: Check if Flag is Enabled/Disabled

// 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

// 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" {
    showExperimentForVariantA()
} else if flagValue as? String == "variant_b" {
    showExperimentForVariantB()
} else {
    showDefaultExperience()
}

Feature Gates: Check if Flag is Enabled/Disabled

// Check if a boolean flag is enabled
let isEnabled = Mixpanel.mainInstance().flags.isEnabledSync("my-boolean-flag", fallbackValue: false)
 
if isEnabled {
    showNewFeature()
} else {
    showOldFeature()
}

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

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 featureFlagsEnabled: true is included in the MixpanelOptions
• If using a custom Variant Assignment Key, ensure it is included in the featureFlagsContext
• If using Runtime Targeting, ensure all properties used in targeting are included in the customProperties object within featureFlagsContext

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