Creating feature flags

This article describes how to create and implement feature flags. If you want to learn more about what feature flags are and how you can use them in Braze, check out About feature flags before proceeding.

Feature flags allow you to remotely enable or disable functionality for a selection of users. Create a new feature flag within the Braze dashboard. Provide a name and an ID, a target audience, and a percentage of users for whom to enable to this feature. Then, using that same ID in your app or website’s code, you can conditionally run certain parts of your business logic.

Prerequisites

To use feature flags, ensure your SDKs are up to date with at least these minimum versions:

Implement feature flags in the dashboard

Create, edit, and archive feature flags from the Feature Flags page, located under Engagement. This page displays a list of existing feature flags for this app group.

Create a new feature flag

To create a new feature flag, click the Create Feature Flag button. Then, define your feature flag’s details, properties, user targeting, and rollout traffic.

Details

Give your new feature flag a Name and ID.

• The Name field allows you to provide a human-readable title for this feature flag that will be used by marketers and administrators.
• The ID field will be referenced in your code to determine whether the feature is enabled for a particular user. This must be unique and cannot be modified once created.
• The Description field is an optional field that allows you to provide additional context around this feature flag.

Choose an ID thoughtfully as it will be used as you develop your feature. Practice good naming conventions to ensure that your code is readable by your colleagues (and your future self).

For example, it’s common to use a naming convention of {verb}_{product}_{feature}, such as enable_rider_new_profile_page to make it clear what enabling the feature flag does.

Properties

Custom properties can be defined as part of your feature flag. These properties will be accessible by your app through the Braze SDK when the feature is enabled. Defining properties is an optional step.

Variables can be strings, boolean values, or numbers. Define both the variable key and default value for each property.

Example properties

For example, if we are defining a feature flag that shows an out-of-stock banner for our ecommerce store, we might set the following properties, which our app will use when displaying the banner:

Targeting

To begin the rollout of a feature flag, you must choose a particular segment of users.

Use the Add Filter dropdown menu to filter users out of your target audience. Add multiple filters to narrow your audience.

Rollout Traffic

Feature flags always start as turned off to allow you to separate the timing of the feature’s release and activation in your users’ experience.

When you are ready to rollout your new feature, specify an audience and then use the Rollout Traffic slider to define the random percentage of your targeted user base to receive the new feature. Set the Rollout Traffic slider to set a percentage between 0% (no users) and 100% (the entire target audience).

Implement the feature flag in your application

Once you have defined your feature flag, configure your app or site to check whether or not it is enabled for a particular user. When it is enabled, you’ll set some action or reference the feature flag’s variable properties based on your use case. The Braze SDK provides getter methods to pull your feature flag’s status and its properties into your app.

Feature flags are refreshed automatically at session start so that you can display the most up-to-date version of your feature upon launch. The SDK caches these values so they can be used while offline.

Let’s say you were to rolling out a new type of user profile for your app. You might set the ID as expanded_user_profile. Then, you would have your app check to see if it should display this new user profile to a particular user. For example:

• Javascript
• Swift
• Java
• Kotlin

1
2
3
4
5
6
const featureFlag = braze.getFeatureFlag("expanded_user_profile");
if (featureFlag.enabled) {
  console.log(`expanded_user_profile is enabled`);
} else {
  console.log(`expanded_user_profile is not enabled`);
}

1
2
3
4
5
6
let featureFlag = braze.featureFlags.featureFlag(id: "expanded_user_profile")
if featureFlag.enabled {
  print("expanded_user_profile is enabled")
} else {
  print("expanded_user_profile is not enabled")
}

1
2
3
4
5
6
FeatureFlag featureFlag = braze.getFeatureFlag("expanded_user_profile");
if (featureFlag.getEnabled()) {
  Log.i(TAG, "expanded_user_profile is enabled");
} else {
  Log.i(TAG, "expanded_user_profile is not enabled");
}

1
2
3
4
5
6
val featureFlag = braze.getFeatureFlag("expanded_user_profile")
if (featureFlag.enabled) {
  Log.i(TAG, "expanded_user_profile is enabled.")
} else {
  Log.i(TAG, "expanded_user_profile is not enabled.")
}

Accessing properties

To access the properties of a feature flag, use one of the following methods depending on the type you defined in the dashboard.

If a feature flag is not enabled, or a property you reference does not exist, these methods will return null.

• Javascript
• Swift
• Java
• Kotlin

1
2
3
4
5
6
7
8
// feature flag instance
const featureFlag = braze.getFeatureFlag("expanded_user_profile");
// string properties
const stringProperty = featureFlag.getStringProperty("color");
// boolean properties
const booleanProperty = featureFlag.getBooleanProperty("expanded");
// number properties
const numberProperty = featureFlag.getNumberProperty("height");

1
2
3
4
5
6
7
8
// feature flag instance
let featureFlag: FeatureFlag = braze.featureFlags.featureFlag(id: "expanded_user_profile")
// string properties
let stringProperty: String? = featureFlag.stringProperty(key: "color")
// boolean properties
let booleanProperty: Bool? = featureFlag.boolProperty(key: "expanded")
// number properties
let numberProperty: Double? = featureFlag.numberProperty(key: "height")

1
2
3
4
5
6
7
8
// feature flag instance
FeatureFlag featureFlag = braze.getFeatureFlag("expanded_user_profile");
// string properties
String stringProperty = featureFlag.getStringProperty("color");
// boolean properties
Boolean booleanProperty = featureFlag.getBooleanProperty("expanded");
// number properties
Number numberProperty = featureFlag.getNumberProperty("height");

1
2
3
4
5
6
7
8
// feature flag instance
val featureFlag = braze.getFeatureFlag("expanded_user_profile")
// string properties
val stringProperty = featureFlag.getStringProperty("color")
// boolean properties
val booleanProperty = featureFlag.getBooleanProperty("expanded")
// number properties
val numberProperty = featureFlag.getNumberProperty("height")

You can also get a list of all enabled feature flags:

• Javascript
• Swift
• Java
• Kotlin

1
2
3
4
const features = getAllFeatureFlags();
for(const feature of features) {
  console.log(`Feature: ${feature.id}`, feature.enabled);
}

1
2
3
4
let features = braze.featureFlags.featureFlags
for let feature in features {
  print("Feature: \(feature.id)", feature.enabled)
}

1
2
3
4
List<FeatureFlag> features = braze.getAllFeatureFlags();
for (FeatureFlag feature: features) {
  Log.i(TAG, "Feature: ", feature.getId(), feature.getEnabled());
}

1
2
3
4
val featureFlags = braze.getAllFeatureFlags()
featureFlags.forEach { feature ->
  Log.i(TAG, "Feature: ${feature.id} ${feature.enabled}")
}

Refresh feature flags

You can refresh the current user’s feature flags mid-session to pull the latest values from Braze.

• Javascript
• Swift
• Java
• Kotlin

1
2
3
4
5
braze.refreshFeatureFlags(() => {
  console.log(`Feature flags have been refreshed.`);
}, () => {
  console.log(`Failed to refresh feature flags.`);
});

1
2
3
4
5
6
7
8
braze.featureFlags.requestRefresh { result in
  switch result {
  case .success(let features):
    print("Feature flags have been refreshed:", features)
  case .failure(let error):
    print("Failed to refresh feature flags:", error)
  }
}

1
braze.refreshFeatureFlags();

1
braze.refreshFeatureFlags()

Listen for changes

You can configure the Braze SDK to listen and update your app when feature flags have been refreshed.

This is useful if you want to update your app if a user is no longer eligible for a feature. For example, setting some state in your app based on whether or not a feature is enabled, or one of its property values.

• Javascript
• Swift
• Java
• Kotlin

1
2
3
4
5
6
// register an event listener
const subscriptionId = braze.subscribeToFeatureFlagsUpdates((features) => {
  console.log(`Features were updated`, features);
});
// unregister this event listener
braze.removeSubscription(subscriptionId);

1
2
3
4
5
6
7
// Create the feature flags subscription
// - You must keep a strong reference to the subscription to keep it active
let subscription = braze.featureFlags.subscribeToUpdates { features in
  print("Feature flags were updated:", features)
}
// Cancel the subscription
subscription.cancel()

1
2
3
4
5
6
braze.subscribeToFeatureFlagsUpdates(event -> {
  Log.i(TAG, "Feature flags were updated.");
  for (FeatureFlag feature: event.getFeatureFlags()) {
    Log.i(TAG, "Feature: ", feature.getId(), feature.getEnabled());
  }
});

1
2
3
4
5
6
braze.subscribeToFeatureFlagsUpdates() { event ->
  Log.i(TAG, "Feature flags were updated.")
  event.featureFlags.forEach { feature ->
    Log.i(TAG, "Feature: ${feature.id}")
  }
}

Best practices

Naming conventions

• Consider following a pattern such as {product}.{feature}.{action}.
  • For example, in a ride sharing app your feature ID may be driver.profile.show_animation_v3
• This also helps when searching for a specific product area or team’s feature flags.
• Make sure that the default state for a feature flag is disabled in your app.
  • For example, it is an anti-pattern if you have a flag named disable_feature_xyz. There may be exceptions, but try to avoid confusing a feature’s “enabled” status with the actual enabled behavior (disabling feature xyz).

Planning ahead

Always play it safe. When considering new features that may require a kill-switch, it’s better to release new code with a feature flag and not need it than it is to realize a new app update is required.

Be descriptive

Add a description to your feature flag. While this is an optional field in Braze, it can help answer questions others may have when browsing available feature flags.

• Contact details for who is responsible for the enablement and behavior of this flag
• When this flag should be disable
• Links to documentation or notes about the new feature this flag controls
• Any dependencies or notes on how to use the feature

Clean up old feature flags

We’re all guilty of leaving features on at 100% rollout for longer than necessary.

To help keep your code (and Braze dashboard) clean, remove permanent feature flags from your code base once all users have upgraded and you no longer need the option to disable the feature.

This helps reduce the complexity of your development environment, but also keeps your list of feature flags tidy.