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 setting the featureFlagsEnabled option to true in 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

MixpanelOptions options = new MixpanelOptions();
options.featureFlagsEnabled = true;
 
MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", options);

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:

JSONObject context = new JSONObject();
context.put("company_id", "X");
 
MixpanelOptions options = new MixpanelOptions();
options.featureFlagsEnabled = true;
options.featureFlagsContext = context;
 
MixpanelAPI mixpanel = MixpanelAPI.getInstance(getApplicationContext(), "YOUR_PROJECT_TOKEN", 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:

JSONObject customProperties = new JSONObject();
customProperties.put("platform", "android");
 
JSONObject context = new JSONObject();
context.put("company_id", "X");
context.put("customProperties", customProperties);
 
MixpanelOptions options = new MixpanelOptions();
options.featureFlagsEnabled = true;
options.featureFlagsContext = context;
 
MixpanelAPI mixpanel = MixpanelAPI.getInstance(getApplicationContext(), "YOUR_PROJECT_TOKEN", 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.

String updatedDistinctId = "";
mixpanel.identify(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:

JSONObject newCustomProperties = new JSONObject();
newCustomProperties.put("platform", "android");
 
JSONObject newContext = new JSONObject();
newContext.put("company_id", "Y");
newContext.put("customProperties", newCustomProperties);
 
// Update the context and reload flags
mixpanel.getOptions().featureFlagsContext = newContext;
mixpanel.getFlags().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
mixpanel.getFlags().getVariantValue("my-feature-flag", "control", new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // This runs on the main thread
        if (value.equals("variant_a")) {
            showExperimentForVariantA();
        } else if (value.equals("variant_b")) {
            showExperimentForVariantB();
        } else {
            showDefaultExperience();
        }
    }
});

FeatureGates: Check if Flag is Enabled/Disabled

// Check if a boolean flag is enabled asynchronously
mixpanel.getFlags().isEnabled("my-boolean-flag", false, 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
Object flagValue = mixpanel.getFlags().getVariantValueSync("my-feature-flag", "control");
 
// Use flag value in your application logic
if (flagValue.equals("variant_a")) {
    showExperimentForVariantA();
} else if (flagValue.equals("variant_b")) {
    showExperimentForVariantB();
} else {
    showDefaultExperience();
}

Feature Gates: Check if Flag is Enabled/Disabled

// Check if a boolean flag is enabled 
boolean isEnabled = mixpanel.getFlags().isEnabledSync("my-boolean-flag", 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 set in MixpanelOptions
• If using a custom Variant Assignment Key, ensure it is included in the featureFlagsContext JSONObject
• 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 logging: Check Android logs for detailed information about flag requests and responses