Working with feature flags and feature rollouts

In Amplitude Experiment, flags drive both experiments and feature rollouts. A flag is a way for you to enable or disable functionality within your product, without having to deploy new code each time—in Amplitude Experiment, this is done by toggling the Active switch on or off. They’re ideal for launching experiments and then ending them once you’ve collected enough data, or for rolling out new features (and rolling them back quickly, if necessary).

This article will explain how to create a flag for a feature rollout. If you’re looking for information on how to use flags in your experiments, see our Help Center article on rolling out your experiment to your users.

Create a new flag

To create a new feature flag, first ensure you’ve created a deployment and installed the SDK. Then follow these steps:

1. From the main Experiment page, either click + New and select Rollout from the drop-down menu, or navigate to the Flags page from the left-hand sidebar and click + Create Rollout.
   
2. In the Create Rollout modal, choose the project that will include this flag from the Projects drop-down menu. Then give your flag a name and a description. This is an identifier for the flag used in your codebase. Amplitude Experiment will automatically generate the flag key from the name you choose. 
   
   
   
   
3. When you’re done, click Create. Experiment will open a blank template for your flag.
4. In the Setup panel, choose the implementation language you’ll be using for this flag—Android, iOS, JavaScript Client, JavaScript Server, or React—from the Language drop-down menu. Experiment will generate code snippets for your codebase, which you can copy and modify as needed.

For more details on working with Experiment SDKs, see the installation guide and the GitHub repository.

5. Next, choose the deployment for your experiment from the Deployment drop-down menu. For more information about working with deployments in Experiment, see this Help Center article.
6. Your flag must have at least one variant. The variant is the new feature or product experience you want to roll out to your users.
   
   When you first create your flag, Experiment automatically generates a variant of true , which will be returned when the flag is active. You can edit this variant. Any other variants you add will have a default value of 'false`, indicating the flag is not active.
   
   You can add as many variants as you need to a feature flag.
   
   To add a variant to your flag, click + Create Variant. The Create Variant modal will appear.
   
   
   
   Type in a name and a description for your variant in the appropriate fields. Experiment will automatically generate the variant value from the name you enter. The variant value is a string that you’ll use as a flag in your codebase. When you’re done, click Create Variant.

NOTE: Do not name your variants OFF. In Amplitude Experiment, this name is reserved for fallbacks (i.e., the user segment not included in your experiments).

7. In the Allocation panel, you can define user segments that will see your new feature, specify the percentage of users you’ll roll it out to, and set the relative distribution weights of each variant.

Defining a user segment is useful if you’d like to limit your rollout to users in a specific geographical location, or those who belong to certain demographic groups, or those who meet certain usage thresholds in your product (i.e., power users).

To define a user segment, scroll down to the Rule Based User Segments section and click into Segment 1. Then follow the same steps you’d use to build a user segment in Amplitude Analytics.

All of Amplitude’s user properties and cohorts are available to use in defining user segments. There is no limit on the number of user segments you can include here.

8. Next, set the rollout percentage for this feature. This is the percentage of the users included in the flag’s user segments who will see the new feature. Choose one of the preset values, or manually enter your desired value. If you want everyone in the user segment to have access to the feature, set this value to 100%.
   
9. After that, you’ll need to tell Experiment how to distribute your variants. This will determine how many users will see each variant. The weights are relative values: for example, if you give variant A a weight of 1 and variant B a weight of 4, then four times as many users will see variant B than variant A.
   
10. You can then set separate rules for everyone not covered by the segment you created in step 7. If, for example, you only want the feature rolled out to the specific cohorts you targeted earlier, scroll down to the All Non-Targeted Users section and set the rollout percentage to zero.
    
    You can see estimates for the total effective distribution of variants across all users in the Summary section.
    
    
11. Next, you’ll want to save your flag, if you haven’t already, and then QA it before setting it to Active. For more information on QAing your flag, see our Help Center article on the subject.
    
12. Finally, when you’re ready, switch the Inactive toggle in the upper-right corner to Active. Your feature is now live for the user segments you selected.