Rollout strategies and targeting rules
Rollout strategies provide an ability to roll out features to a segment of audience based on targeting rules. For example, 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 turn your feature "on" only to 50% of the audience.
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". If 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. See Rollout strategies evaluation order for details on strategies ordering.
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
Preset rules are defined in FeatureHub SDKs and can be accessed via SDK functions, e.g. in JS SDK
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 Preset rules do not satisfy your requirements you also have an ability to attach a custom rule.
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.
To create a custom rule, select "Add split targeting rules" from the Feature editing menu and select "Custom" option. Enter "custom key", for example
languages, set the type, e.g.
string, a matching condition, e.g.
equals and provide matching value or a list of values, e.g.
english, spanish, french
When you need to evaluate a user in the SDK, you can pass the "custom key" and user attributes (in this case language attribute values), e.g. in JS SDK:
await fhContext.attributeValue('languages', 'italian').build();
or for an array of values:
await fhContext.attributeValue('languages', ['italian', 'english', 'german']).build();
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.
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 Google Analytics 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
sessionId or a
userKey, ideally consistent for the user across platforms). It uses
an algorithm to spread that across a range giving you control down to four decimal points, but the algorithm is more accurate
the greater the number of clients you have. i.e. you can roll out to 0.0001% of your usage base if you wish.
If you only have five users, this probably won’t turn a feature "on" for anyone, if you have a million it will
be more accurate.
As you can assign multiple rollout strategies to a feature, the order of the strategies becomes important. Strategies evaluated in order from first to last (in the Admin UI, as they are displayed from top to bottom), and stops when it hits a matching one. If no strategies match, then "default" feature value is served. Strategies order can be set by dragging them in the Admin UI console - feature editing panel.