MixpanelFlags

public protocol MixpanelFlags

A protocol defining the public interface for a feature flagging system.

  • The delegate responsible for handling feature flag lifecycle events, such as tracking. It is declared weak to prevent retain cycles.

    Declaration

    Swift

    var delegate: MixpanelFlagDelegate? { get set }

  • Initiates the loading or refreshing of flags

    Declaration

    Swift

    func loadFlags()

  • Initiates the loading or refreshing of flags with a completion callback. The completion handler is called with true on success and false on failure.

    Declaration

    Swift

    func loadFlags(completion: ((Bool) -> Void)?)

  • Synchronously checks if the flags have been successfully loaded and are available for querying.

    Declaration

    Swift

    func areFlagsReady() -> Bool

    Return Value

    true if the flags are loaded and ready for use, false otherwise.

  • Synchronously retrieves the complete MixpanelFlagVariant for a given flag name. If the feature flag is found and flags are ready, its variant is returned. Otherwise, the provided fallback MixpanelFlagVariant is returned. This method will also trigger any necessary tracking logic for the accessed flag.

    Important

    This method may block the calling thread until the value can be retrieved. It is NOT recommended to call this from the main UI thread. If flags are not ready (areFlagsReady() is false), this method returns the fallback value, but it may still block while waiting for queued tracking or activation work to complete. If called immediately after track(), variants may not be activated yet due to a race condition as track is executed asynchronously. Use getVariant instead.

    Declaration

    Swift

    func getVariantSync(_ flagName: String, fallback: MixpanelFlagVariant) -> MixpanelFlagVariant

    Parameters

    flagName

    The unique identifier for the feature flag.
    fallback

    The MixpanelFlagVariant to return if the specified flag is not found or if the flags are not yet loaded.

    Return Value

    The MixpanelFlagVariant associated with flagName, or the fallback variant.

  • Asynchronously retrieves the complete MixpanelFlagVariant for a given flag name. If flags are not ready, an attempt will be made to load them. The completion handler is called with the MixpanelFlagVariant for the flag, or the fallback variant if the flag is not found or loading fails. This method will also trigger any necessary tracking logic for the accessed flag. The completion handler is typically invoked on the main thread.

    Declaration

    Swift

    func getVariant(
  _ flagName: String, fallback: MixpanelFlagVariant,
  completion: @escaping (MixpanelFlagVariant) -> Void)

    Parameters

    flagName

    The unique identifier for the feature flag.
    fallback

    The MixpanelFlagVariant to use as a default if the specified flag is not found or an error occurs during fetching.
    completion

    A closure that is called with the resulting MixpanelFlagVariant. This closure will be executed on the main dispatch queue.

  • Synchronously retrieves the underlying value of a feature flag. This is a convenience method that extracts the value property from the MixpanelFlagVariant obtained via getVariantSync.

    Important

    This method may block the calling thread until the value can be retrieved. It is NOT recommended to call this from the main UI thread. If flags are not ready (areFlagsReady() is false), this method returns the fallbackValue, but it may still block while waiting for queued tracking or activation work to complete. If called immediately after track(), variants may not be activated yet due to a race condition as track is executed asynchronously. Use getVariantValue instead.

    Declaration

    Swift

    func getVariantValueSync(_ flagName: String, fallbackValue: Any?) -> Any?

    Parameters

    flagName

    The unique identifier for the feature flag.
    fallbackValue

    The default value to return if the flag is not found, its variant doesn’t contain a value, or flags are not ready.

    Return Value

    The value of the feature flag, or fallbackValue. The type is Any?.

  • Asynchronously retrieves the underlying value of a feature flag. This is a convenience method that extracts the value property from the MixpanelFlagVariant obtained via getVariant. If flags are not ready, an attempt will be made to load them. The completion handler is called with the flag’s value or the fallbackValue. The completion handler is typically invoked on the main thread.

    Declaration

    Swift

    func getVariantValue(
  _ flagName: String, fallbackValue: Any?, completion: @escaping (Any?) -> Void)

    Parameters

    flagName

    The unique identifier for the feature flag.
    fallbackValue

    The default value to use if the flag is not found, fetching fails, or its variant doesn’t contain a value.
    completion

    A closure that is called with the resulting value (Any?). This closure will be executed on the main dispatch queue.

  • Synchronously checks if a specific feature flag is considered “enabled”. This typically involves retrieving the flag’s value and evaluating it as a boolean. The exact logic for what constitutes “enabled” (e.g., true, non-nil, a specific string) should be defined by the implementing class.

    Important

    This method may block the calling thread until the value can be retrieved. It is NOT recommended to call this from the main UI thread. If flags are not ready (areFlagsReady() is false), this method returns the fallbackValue, but it may still block while waiting for queued tracking or activation work to complete.

    Declaration

    Swift

    func isEnabledSync(_ flagName: String, fallbackValue: Bool) -> Bool

    Parameters

    flagName

    The unique identifier for the feature flag.
    fallbackValue

    The boolean value to return if the flag is not found, cannot be evaluated as a boolean, or flags are not ready. Defaults to false.

    Return Value

    true if the flag is considered enabled, false otherwise (including if fallbackValue is used).

  • Asynchronously checks if a specific feature flag is considered “enabled”. This typically involves retrieving the flag’s value and evaluating it as a boolean. If flags are not ready, an attempt will be made to load them. The completion handler is called with the boolean result. The completion handler is typically invoked on the main thread.

    Declaration

    Swift

    func isEnabled(_ flagName: String, fallbackValue: Bool, completion: @escaping (Bool) -> Void)

    Parameters

    flagName

    The unique identifier for the feature flag.
    fallbackValue

    The boolean value to use if the flag is not found, fetching fails, or it cannot be evaluated as a boolean. Defaults to false.
    completion

    A closure that is called with the boolean result. This closure will be executed on the main dispatch queue.

  • Synchronously retrieves all currently fetched feature flag variants. Returns an empty dictionary if flags have not been loaded yet. This method does not trigger tracking for any flags.

    Important

    This method may block the calling thread until the value can be retrieved. It is NOT recommended to call this from the main UI thread. If flags are not ready (areFlagsReady() is false), it returns an empty dictionary immediately without fetching, but it may still block while waiting for queued tracking or activation work to complete. If called immediately after track(), variants may not be activated yet due to a race condition as track is executed asynchronously. Use getAllVariants instead.

    Declaration

    Swift

    func getAllVariantsSync() -> [String : MixpanelFlagVariant]

    Return Value

    A dictionary mapping flag names to their MixpanelFlagVariant values, or an empty dictionary if flags are not ready.

  • Asynchronously retrieves all feature flag variants. If flags are not ready, an attempt will be made to load them. This method does not trigger tracking for any flags. The completion handler is typically invoked on the main thread.

    Declaration

    Swift

    func getAllVariants(completion: @escaping ([String : MixpanelFlagVariant]) -> Void)

    Parameters

    completion

    A closure that is called with a dictionary mapping flag names to their MixpanelFlagVariant values. Returns an empty dictionary if fetching fails.

  • Replaces the current custom flag evaluation context entirely and triggers a flag re-fetch.

    Declaration

    Swift

    func setContext(_ context: [String : Any], completion: @escaping () -> Void)

    Parameters

    context

    The new context dictionary to use for flag evaluation.
    completion

    A closure called when the fetch completes (success or failure).