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 a function or feature in your product, without having to deploy new code each time. In Amplitude Experiment, toggle the Active switch on or off to do this. Flags are ideal for launching experiments and ending them once you’ve collected enough data, or for rolling out new features (and rolling them back quickly, if you need to).

This article will explain how to create a flag for a feature rollout. If you need 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

You cannot create a new feature flag until you’ve created a deployment and installed the SDK. Once you've done that, 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 Flag.
   
2. In the Create Flag 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. Specify the evaluation mode for your experiment, either Remote (i.e., it will be evaluated on Amplitude servers) or Local. Then specify the bucketing unit you want to use for this experiment.
   
   TIP: The best bucketing unit will usually be the user. However, in some B2B use cases, you might want to use company ID or city as the bucketing unit. For example, bucketing by company ID ensures that all users in a particular company will have the same user experience. Be sure the Stable Unit Treatment Value Assumption holds for whichever unit you choose.
   
   
4. When you’re done, click Create. Experiment will open a blank template for your flag.
5. Next, on the Configure tab, choose the deployment for your experiment from the Deployment drop-down menu. For more information about working with deployments, see this article on configuring Amplitude Experiment.
6. In Advanced Settings, you can change the bucketing salt. But if you do, users might switch between variants in your experiment. For that reason, we recommend you do not change the bucketing salt unless you know what you're doing. For more information, see our Help Center article on how randomization works in Amplitude Experiment.
7. 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, Amplitude 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. Amplitude 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. You’ll need to tell Amplitude Experiment 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 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, save your flag, if you haven’t already, and QA it before setting it to Active. For more information, see our Help Center article on QAing flags in Amplitude Expermient.
    
12. 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.