Skip to main content

Strategy Variants

Availability

Strategy variants were first introduced in Unleash 5.4.

Gradual rollout strategies in Unleash can have strategy variants. Strategy variants allow each matching activation strategy to return not just simple enabled/disabled status, but also attach any custom data or even multiple data items.

What are strategy variants?​

Whenever you create a feature activation strategy, you can assign it one or more values called variants. This is commonly done in cases where you want to serve your users additional information related to the matching strategy. Also it's possible to assign multiple variants to one strategy to see which performs better.

A variant has four components that define it:

  • a name:

    This must be unique among the strategy's variants. When working with a feature with variants in a client, you will typically use the variant's name to find out which variant it is.

  • a weight:

    The weight is the likelihood of any one user getting this specific variant. See the weights section for more info.

  • an optional payload:

    A variant can also have an associated payload. Use this to deliver more data or context. See the payload section for a more details.

A form for adding new strategy variants. It has fields for name, weight, payload.

Variant weight​

A variant's weight determines how likely it is that a user will receive that variant. It is a numeric value between 0 and 100 (inclusive) with one decimal's worth of precision.

When you have multiple variants, the sum of all their weights must add up to exactly 100. Depending on the weight type, Unleash may automatically determine the weight of the new variant and balance it out with the other variants.

Weight types and calculation​

There are two kinds of variant weight types: variable and fixed. Unleash requires you to always have at least one variable weight variant.

The default weight type is variable. Variable weight variants will adjust their weight based on the number of other variable weight variants and whatever weight is not used up by fixed weight variants.

Fixed weight variants have a set weight which will not change. All fixed weight variants' weights can not add up to more than 100.

To calculate what the weight of a variable weight variant is, Unleash first subtracts the sum of fixed weights from 100 and then distributes the remaining weight evenly among the variable weight variants.

For instance, if you have three variable weight variants and two fixed weight variants weighted at 25 and 15 respectively, Unleash will:

  1. Subtract the fixed weight from the total available: 100 - 40 = 60
  2. Divide the remainder by the number of variable weight variants: 60 / 3 = 20
  3. Assign each variable weight variant the same (up to rounding differences) weight: 20%

In the example above, 60 divides cleanly by three. In cases where the remainder doesn't divide evenly among the variable weight variants, Unleash will distribute it as evenly as it can to one decimal's precision. If you have three variable weight variants, they will be weighted at 33.4, 33.3, and 33.3 respectively, so that it adds up to 100.0.

Variant payload​

Each variant can have an associated payload. Use this to add more context or data to a payload that you can access on the client, such as a customized message or other information.

Unleash currently supports these payload types:

  • JSON
  • CSV
  • String

Variant stickiness​

When you have only one variant in a strategy, stickiness does not matter. If you decide to add multiple variants to the strategy, then variant stickiness is derived from the strategy stickiness. Strategy stickiness is calculated on the received user and context, as described in the stickiness chapter. This ensures that the same user will consistently see the same variant. If no context data is provided, the traffic will be spread randomly for each request.

If you would like to reassign users to different variants using existing stickiness parameter then you can change the groupId of the strategy. This will provide different input to the stickiness calculation.

Strategy variants vs feature toggle variants​

Strategy variants take precedence over the feature flag variants. If your matching activation strategy doesn't have any variants configured you will fall back to the feature flag variants. Since strategy variants are part of activation strategies they have full access to constraints and segments. Feature variants are much more limited since they only allow simple overrides.

How do I configure strategy variants​

In the Unleash UI, you can configure variants by navigating to the gradual strategy view, and then choosing the 'Variants' section.

strategy_variants

The disabled variant​

When your matching strategy has no variants or when your flag has no variants or when a flag is disabled for a user, Unleash will return variant data that looks like this:

{
  "name": "disabled",
  "enabled": false
}

This is a fallback variant that Unleash uses to represent the lack of a variant.

Note: The actual representation of the built-in fallback variant in the client SDK will vary slightly, to honor best practices in various languages.

Strategy variants and strategies order​

When you add multiple activation strategies, each having its own variants defined, the order of strategies matters. Unleash chooses the first matching strategy. It is common to define your specific activation strategies with explicit constraints and segments first. The specific strategies can be followed by a broad activation strategy with multiple percentage based variants.

In the example below we configure fixed title for the internal users based on the clientId constraint. In the second strategy we split titles between all other users based on the 50%/50% split. strategy_variants example

Client SDK Support​

To make use of strategy variants, you need to use a compatible client. Client SDK with variant support:

If you would like to give feedback on this feature, experience issues or have questions, please feel free to open an issue on GitHub.