Percentage Options
What are Percentage Options?
Using Percentage Options, you can define that a certain percentage of users should receive a specific value.
This way, you can gradually release a new feature to a subset of users. Instead of releasing a feature to all users simultaneously, a specific percentage of users are selected to receive access to the feature. This allows developers to control and monitor the impact of the new feature in a controlled manner.
How to add Percentage Options?
You can add Percentage Options to a feature flag by clicking the +% button on the Dashboard.
How does it work? - Anatomy of Percentage Options
Percentage Options is a list of % value and served value pairs, where % values add up to 100.
It divides users into groups according to the percentage split defined by the % values. The grouping is random and based on the Percentage Evaluation Attribute. By default, this is the User Object's Identifier attribute. However, you can use any other user attribute as the basis of the grouping.
If the Percentage Evaluation Attribute is not present in the User Object, the "To unidentified" value will be returned. (Read more about the feature flag evaluation algorithm here.)
Percentage Options are designed to be sticky and consistent across all SDKs, ensuring a reliable experience.
% value
Any number between 0 and 100 that represents a randomly allocated group of your users.
Served value
The value to return when the user falls into the group determined by the % value.
Number of Percentage Options
In the case of a feature flag (boolean setting), there must be two options. One for the ON and one for the OFF state.
In the case of a string, integer or double setting, the maximum number of options depends on your subscription plan. You can add options by clicking the +% OPTION button.
Percentage Options within Targeting Rules
Percentage Options can be used in combination with Targeting Rules.
In this case, the Percentage Options will be evaluated only if the Targeting Rule matches. In other words, the Percentage Options apply only to the users that matched the Targeting Rule.
If the Percentage Evaluation Attribute is not present in the User Object, the targeting rule will be skipped - despite the matching Targeting Rule. Read more about the feature flag evaluation algorithm here.
Percentage Evaluation Attribute
The Percentage Evaluation Attribute (sometimes called percentage attribute) is the user attribute by which users are grouped. By default, it is the User Object's Identifier attribute. However, you can use any other user attribute as the basis of the grouping (see the example use case below).
How to change the Percentage Evaluation Attribute?
In the top right corner of the feature flag, open the kebab (3 dots) menu and choose the Change percentage attribute item.
The selected Percentage Evaluation Attribute applies to all Percentage Options within the feature flag - but only in the current ConfigCat environment.
Stickiness
Stickiness means that the same user will always get the same value for the same percentage split in the case of a specific feature flag, regardless of the history of the feature flag. This is achieved by implementing a deterministic hashing algorithm based on the feature flag's key and the Percentage Evaluation Attribute.
For example, if you have a feature flag with a Percentage Option of 20% ON, then you change the Percentage Option to 40% ON, and then back to 20% ON, the same 20% of users will get the ON value for the feature flag just like the first time.
For a demonstration of this concept, see this example scenario.
Consistency
Consistency means that the same user will always get the same value for the same percentage split in the case of a specific feature flag, no matter which SDK is used. This is achieved by using the same hashing algorithm across all SDKs.
For example, if you have a feature flag with a Percentage Option of 20% ON, then the same 20% of users will get the ON value across all SDKs. No matter if a user is on iOS, Android, or Web, they will always get the same value for the feature flag.
Randomness
The same user might get different values for the same percentage split in the case of different feature flags. This is because the hashing algorithm is based on the combination of the feature flag's key and the Percentage Evaluation Attribute. Since feature flag keys are unique, the resulting hashes will usually be different as well.
For example, if you have two feature flags with Percentage Options of 20% ON, then a different 20% of users will get the ON value for each feature flag.
Examples
Simple phased rollout / Canary release / Percentage rollout scenario
Context
Our demo company, Whisker Co. is about to release a new feature called Park Weather Info. The stakeholders want to make sure that the new feature is received well by the customers.
Goal
To get some feedback from our customers before releasing it to everyone, we initially want to make the feature available to 20% of the customers only.
Solution
Let's create a feature flag called Enable Park Weather Info with Percentage Options set to 20% ON and 80% OFF.
A/B/n testing scenario
Context
The marketing specialists at Whisker Co. want to introduce a discount strategy to boost webshop purchases. They have several ideas but lack the statistical data needed to determine which would be most effective.
Goal
To learn which is the most effective discount strategy, we want to perform an A/B/C test.
Solution
We need a string or integer setting for this task because we need to represent 3 different variations. Let's create a string setting named Discount Type (as textual values tell more than numbers).
The go-to feature for A/B testing is Percentage Options. So let's add one with 3 options, each covering 1/3rd of our customers.
Complex phased rollout / Canary release / Percentage rollout scenario
Context
Whisker Co. is about to release a new feature called Park Weather Info. The stakeholders want to make sure that the release of the new feature goes smoothly and it is received well by the customers.
Goal
To do some in-house testing and also get some feedback from our customers before releasing it to everyone, we initially want to make the feature available to the employees and to 20% of the customers only.
Solution
Let's create a feature flag called Enable Park Weather Info with a Targeting Rule that matches the employees at Whisker Co. and Percentage Options set to 20% ON and 80% OFF for the rest of the users (i.e. for the customers).
Platform-specific phased rollout
Context
Whisker Co. is about to release a new feature called Cafe Notifications in their mobile app, which has an Android and an iOS version. We know that the userbase of the iOS app is much larger than the Android app. The stakeholders want to make sure that the new feature is received well by the customers.
Goal
To get some feedback from our customers before releasing it to everyone, we initially want to make the feature available to a limited number of customers only. We also want to release the feature to roughly the same number of Android and iOS users.
Solution
Let's create a feature flag called Cafe Notifications with two Targeting Rules: one that matches Android users and one that matches iOS users. Then change the THEN part of both to Percentage Options. Finally, let's set the percentages so that the feature is enabled for roughly the same number of users (e.g. 60% for Android users, 20% for iOS users).
Percentage Options based on other user attributes
Context
Let's imagine that at Whisker Co., we have a custom attribute named Tenant ID that is used to identify the tenants of our customers.
Goal
We want to release a new feature, Park Weather Info, to 20% of our customers based on their Tenant ID.
Solution
Let's create a feature flag called Enable Park Weather Info with Percentage Options set to 20% ON and 80% OFF. Finally, let's set the Percentage Evaluation Attribute to Tenant ID as described here.
