Implement Feature Flags (Android)

Overview

This developer guide will assist you in configuring your Android platform for Feature Flags using the Mixpanel Android 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 Android SDK documentation, see the Android 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 v8.2.4). 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 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

Java

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", false, options);

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:

Java

JSONObject context = new JSONObject();
context.put("company_id", "X");

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .context(context)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(getApplicationContext(), "YOUR_PROJECT_TOKEN", false, 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:

JSONObject customProperties = new JSONObject();
customProperties.put("platform", "android");

JSONObject context = new JSONObject();
context.put("company_id", "X");
context.put("custom_properties", customProperties);

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .context(context)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(getApplicationContext(), "YOUR_PROJECT_TOKEN", false, options);

Flag Persistence

Minimum supported SDK version: v8.7.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 SharedPreferences so they are available immediately on subsequent launches.

Configure a variantLookupPolicy on the FeatureFlagOptions builder:

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

Java

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .variantLookupPolicy(VariantLookupPolicy.networkFirst())
    .build();

// getVariantValue waits for the network. Falls back to persisted value if network fails.
mixpanel.flags.getVariantValue("my-feature-flag", "control", new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // 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.

Java

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .variantLookupPolicy(VariantLookupPolicy.persistenceUntilNetworkSuccess())
    .build();

// getVariantValue returns immediately from persistence. Each call triggers a background fetch
// until a network response succeeds and replaces the persisted state.
mixpanel.flags.getVariantValue("my-feature-flag", "control", new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // value is from persistence; background fetch retries on each call until network succeeds
    }
});

To customize the TTL (default: 24 hours), pass the value in milliseconds:

Java

long ttlMs = 12 * 60 * 60 * 1000L; // 12 hours
FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .variantLookupPolicy(VariantLookupPolicy.networkFirst(ttlMs))
    .build();

Variant source

Every MixpanelFlagVariant carries a source field indicating where the value came from: Source.Network, Source.Persistence, or Source.Fallback. Use getVariant() to receive the full variant object.

Java

MixpanelFlagVariant fallback = new MixpanelFlagVariant("control", "control");
mixpanel.flags.getVariant("my-feature-flag", fallback, new FlagCompletionCallback<MixpanelFlagVariant>() {
    @Override
    public void onComplete(MixpanelFlagVariant variant) {
        Object value = variant.value;
        MixpanelFlagVariant.Source source = variant.source; // Network, Persistence, 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)

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.

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.

String updatedDistinctId = "";
// Reload after login
mixpanel.identify(updatedDistinctId);

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

// Manually reload flags if desired
mixpanel.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.

Map<String, Object> newContext = new HashMap<>();
newContext.put("company_id", "Y");

Map<String, Object> customProperties = new HashMap<>();
customProperties.put("platform", "android");
newContext.put("custom_properties", customProperties);

mixpanel.flags.setContext(newContext, new FlagCompletionCallback<Boolean>() {
    @Override
    public void onComplete(Boolean success) {
        // 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 v8.7.0 or later.

mixpanel.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(false):

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .prefetchFlags(false)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", false, options);

// Flags will not be fetched until identify() or loadFlags() is called
mixpanel.identify("user-123");

When prefetchFlags is set to false, flags will not be loaded until you explicitly call identify() or mixpanel.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 if the user context is in a rollout group for the feature flag.

Asynchronous Flag Variant Retrieval

Experiment Flags: Get Variant Value

// Get just the flag value asynchronously
String fallback = "control"; // the value to use if the user doesn't match any of the flag's rollout rules
mixpanel.flags.getVariantValue("my-feature-flag", fallback, new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // This runs on the main thread
        if (value.equals("variant_a")) {
            showExperienceForVariantA();
        } else if (value.equals("variant_b")) {
            showExperienceForVariantB();
        } else {
            showDefaultExperience();
        }
    }
});

FeatureGates: Check if Flag is Enabled/Disabled

// Check if a boolean flag is enabled asynchronously
boolean fallback = false; // the value to use if the user doesn't match any of the flag's rollout rules
mixpanel.flags.isEnabled("my-boolean-flag", fallback, new FlagCompletionCallback<Boolean>() {
    @Override
    public void onComplete(Boolean isEnabled) {
        // This runs on the main thread
        if (isEnabled) {
            showNewFeature();
        } else {
            showOldFeature();
        }
    }
});

Synchronous Flag Variant Retrieval

Experiment Flags: Get Variant Value

// Get just the flag value synchronously
String fallback = "control"; // the value to use if the user doesn't match any of the flag's rollout rules
Object flagValue = mixpanel.flags.getVariantValueSync("my-feature-flag", fallback);

// Use flag value in your application logic
if (flagValue.equals("variant_a")) {
    showExperienceForVariantA();
} else if (flagValue.equals("variant_b")) {
    showExperienceForVariantB();
} else {
    showDefaultExperience();
}

Feature Gates: Check if Flag is Enabled/Disabled

// Check if a boolean flag is enabled
boolean fallback = false; // the value to use if the user doesn't match any of the flag's rollout rules
boolean isEnabled = mixpanel.flags.isEnabledSync("my-boolean-flag", fallback);

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 Map<String, MixpanelFlagVariant> containing all current flag assignments. If flags have not been loaded yet, it returns an empty map.

Map<String, MixpanelFlagVariant> allFlags = mixpanel.flags.getAllVariantsSync();

for (Map.Entry<String, MixpanelFlagVariant> entry : allFlags.entrySet()) {
    Log.d("Flags", entry.getKey() + ": " + entry.getValue().value);
}

Asynchronous

getAllVariants() returns a Map<String, MixpanelFlagVariant> via a callback. If flags have not been loaded yet, it will attempt to fetch them before returning.

mixpanel.flags.getAllVariants(new FlagCompletionCallback<Map<String, MixpanelFlagVariant>>() {
    @Override
    public void onComplete(Map<String, MixpanelFlagVariant> allFlags) {
        for (Map.Entry<String, MixpanelFlagVariant> entry : allFlags.entrySet()) {
            Log.d("Flags", entry.getKey() + ": " + entry.getValue().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

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 is configured with .enabled(true) and passed to MixpanelOptions
• If using a custom Variant Assignment Key, ensure it is included in the FeatureFlagOptions .context() JSONObject
• 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 logging: Check Android logs for detailed information about flag requests and responses