Rollout strategies and targeting rules
Rollout strategies provide an ability to roll out features to a limited audience based on targeting rules, for example imagine you have a feature flag of type string which controls a "button color" that can be in multiple states,
e.g. green, blue, red etc. With rollout strategies, you can serve a
green value to users on
blue value to users whose emails ending with
red value to users whose location is
New Zealand or United States or United Kingdom. You can also use percentage based rollouts and for example, turn your feature "on" only to 50% of the audience.
Rollout strategies are created and added per Feature value. Once you add a strategy you can set a feature value to serve to users that will match this strategy, for example "on" or "off". In case a user doesn’t match any of the provided strategies, they will be served a "default value". You can change the default strategy and rollout strategy feature values at any time (given you have permissions).
You can apply zero or more rollout strategies to a feature. Each rollout strategy can be assigned a different feature value.
A rollout strategy consists of one or more targeting rules. The rule can consist of any combination of matching criteria.
Each additional rule is always applied as an
AND condition - the user is using a mobile device that is iOS
their country is Australia.
Example of a targeting rule
Each rule is essentially a key, a condition (equals, includes, etc) and zero or more values. Whereas each rule
AND condition, each value is an
OR condition. For example, if the
AND the custom field
payment_method is equal to
Each rollout strategy can have zero or more rules associated with it. If it has zero rules and no percentage rule the strategy will be ignored. There is no limit on how many rules you can apply. There are 3 main rule types: Preset, Custom and Percentage split
Targeting rule types
Available list of countries to match on
Available values to match on:
browser, mobile, desktop, server, watch, embedded
Available values to match on:
linux, windows, macos, android, ios
For example, can be used to match on email address, partial email address, user id, partial user id or regex.
Requires to be in semantic version format, e.g.
1.2.0 - read more about semantic versioning here
If you cannot find a suitable rule from those listed above, you can create your own rule. When setting up a custom rule you will be required to select a rule type.
Supported custom rules types:
number - any valid number
boolean - true and false
semantic version - as per semantic version format. If you are only targeting Java you also get the additional formats supported by Maven and Gradle.
date - international format only -
date-time - international format only -
YYYY-MM-DDTHH:MM:SS.NNN with an optional timezone, UTC is assumed
ip-address - CIDR or specific IP addresses are supported.
Note, if you do not set the value in the user context in the SDK, and the rule indicates to match
blank value then this rule will evaluate to true.
Percentage split rule
As well as setting up targeting rules you can also set up a special rule type - percentage split. Percentage rules lets you roll out a feature value to an approximate percentage of your user base.
A typical scenario for a flag for example would be a "soft launch". The "default value" of your flag would be
off and you set some arbitrary percentage
on (e.g. 20%). Then you would analyse how your feature is performing for those 20%, collect any user feedback, monitor your logging for any issues and if you are happy you will start
increasing the rollout to more and more people in your user base, eventually setting it to 100%, changing the default to
"on" and removing the strategy. (This is set per environment).
In case of multiple rollout strategies assigned to a feature that contain percentage split rules, the sum of all of them cannot be over 100%. If you add percentage based rollout strategies that do not add to 100%, then the remainder continues to use the default value.
You can also use percentage rules to perform A-B testing or run experiments. Given FeatureHub provides a GoogleAnalytics connector - you can see the result of your experimentation in the Google Analytics Events dashboard in real time.
Percentage rules can be mixed with other rules, for example a strategy can have a country rule and a percentage rule, e.g. turn on the feature flag to 25% of the audience in New Zealand.
For Percentage rule to work you need to set a
userKey when implementing feature flags through our SDKs.
userKey can be anything that identifies your user, e.g
It is important to note that the percentages are an approximation, the algorithm works by taking user Context data you provide
in SDK in the client side (either a
Rollout strategies order
As you can assign multiple rollout strategies to a feature, the order of the strategies becomes important. The SDK applies the strategies in order from first to last, and stops when it hits a matching one. Strategies order can be set by dragging them in the Admin UI console - feature editing panel.