Rollout strategies and targeting rules

Rollout strategies

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 iOS devices, blue value to users whose emails ending with gmail.com and 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.

Split targeting

Targeting rules

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 AND their country is Australia.

Example of a targeting rule

Split targeting

Each rule is essentially a key, a condition (equals, includes, etc) and zero or more values. Whereas each rule is an AND condition, each value is an OR condition. For example, if the country is New Zealand OR Indonesia AND the custom field payment_method is equal to credit_card OR direct_debit.

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

Preset rules

Preset rules are defined in FeatureHub SDKs and can be accessed via SDK functions, e.g. in JS SDK await fhContext.country(StrategyAttributeCountryName.NewZealand).build();

  • Country

Available list of countries to match on

  • Device

Available values to match on: browser, mobile, desktop, server, watch, embedded

  • Platform

Available values to match on:

linux, windows, macos, android, ios

  • User Key

For example, can be used to match on email address, partial email address, user id, partial user id or regex.

  • Version

Requires to be in semantic version format, e.g. 1.2.0 - read more about semantic versioning here

Custom

If Preset rules do not satisfy your requirements you also have an ability to attach a custom rule.

Supported custom rules types:

string

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 - YYYY-MM-DD

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

Split targeting custom rule

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.

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 to 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 Context with sessionId or userKey when implementing feature flags through our SDKs. userKey can be anything that identifies your user, e.g userId, email etc..

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.

Rollout strategies evaluation order

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.

Split targeting