• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""


Percentage rollouts

Read time: 3 minutes
Last edited: Jun 17, 2022


This topic explains how to use percentage rollouts to release new features to users incrementally.

Percentage rollouts let you manage the risk of deployment by releasing a feature to users gradually. You can roll out your feature to a small percentage of random users and, as you become more confident your feature is working as intended, increase the percentage over time.

Creating percentage rollouts

You can create a percentage rollout in a flag's targeting rule or a flag's default rule.

Here is an image of a percentage rollout in a default rule:

The percentage rollout section.
The percentage rollout section.

In this example, 25% of users will receive the new feature. If the new feature works as expected, you can increase the percentage of users receiving the new feature incrementally, until it eventually reaches 100%.

If you want to roll out a variation to a very small percentage of your users, you can assign less than 1% to a variation. You can use up to three decimal places, for example, 0.125%.

You can use workflows to automate the process of changing rollout percentages over time. To learn how, read Workflows.

Understanding percentage rollout logic

When you set up a percentage rollout, each user receives a particular variation based on their user key.

The percentage rollout logic generates a hash based on both user attributes and the flag's key. The SDK uses this hash to generate a percentage value for that user. That value, compared to the value set for the percentage rollout value, determines which variation a user receives. The hash has partitions from 1 to 100,000. When you assign flag variations, the hash assigns values from 1 to 100,000 to users in each partition, in order. For example, when you assign 50% to variation A, LaunchDarkly serves variation A to hash partitions from 1 to 50,000.

A common use case for percentage rollouts is to increment the percentage of users targeted by a flag over time until 100% of the users receive one variation of a flag. When you change the percentage allocation of users to flag variations, those users are reassigned different flag variations based on their partition's position in the 1 to 100,000 hash list. For example, if you change the percentage of users receiving variation A from 50% to 70%, partitions 50,001 to 70,000 would be added to the set of partitions already receiving variation A.

To learn more about rollouts and variation assignments, read Percentage rollouts.

Using advanced rollouts

You can assign variations to users based on any user attribute in the Advanced menu.

For example, you can roll out a feature to 25% of users, but instead of being assigned to a variation randomly, users will be assigned to a variation based on the value of their country attribute. This ensures that LaunchDarkly assigns all users with matching attribute-value pairs to the same variation.

Here is an image of an advanced rollout:

An advanced percentage rollout.
An advanced percentage rollout.

The attribute must have either string values or integer numeric values. If you use a custom attribute with a numeric value that includes a fraction, or has a value type besides string or number, then the SDK cannot use the attribute value and assigns the user to an arbitrary variation.

Maintaining user experience across anonymous and logged-in states

To associate pre-login (anonymous user) behaviors with post-login (known user) behaviors to get a singular view of a user flow, you should use a custom attribute and the advanced option for percentage rollouts that allows you to rollout based on a different attribute.

Here's how to do this:

  1. Store a unique identifier for the anonymous user into a cookie. A session ID or UUID works well.
  2. Use this unique identifier as both the user's key and a custom attribute until the user logs in. The custom attribute can be named anything, but for this example it is named uniqueId.
  3. While the user is logged in, set the user's key to their real (primary) user key, but continue to use the unique identifier stored in the cookie as the user's uniqueId custom attribute.
  4. For all flags, or for those that may affect logged out users, use the advanced option for all percentage rollouts to do rollouts based on the uniqueId custom attribute.

To learn more about anonymous users, read Anonymous users.

Secondary attribute

The secondary attribute is a special attribute. The SDKs incorporate this attribute into the variation bucket assignment hash automatically when it is included in your user object. Unlike other attributes, you cannot use the secondary attribute in targeting rules.