Percentage rollouts
Release a variant to a share of users with sticky, deterministic bucketing.
A percentage rollout is a rule that serves variants by weight, for example on to 20% of users and off to 80%. Each user always lands in the same group, so the experience stays consistent across requests, servers, and SDKs.
Add a rollout
In the dashboard:
- Open the flag and select the environment tab.
- In Who gets what, select Add rule, or use an existing rule.
- Under Gets, choose Split by percentage. The split starts at 50% for the rule's variant and 50% for another variant.
- Set a percentage for each variant. To add another variant to the split, select Add variant.
- Optionally, change the attribute after Same user, same variant: bucket by. The default is
targetingKey. - Select Save environment.
A rollout rule can also have conditions and segments. Then the rollout applies only to users who match them. For example, "20% of users on the pro plan".
In the API, a rollout is a serve object of type rollout:
{
"type": "rollout",
"bucketBy": "targetingKey",
"splits": [
{ "variant": "on", "weight": 20 },
{ "variant": "off", "weight": 80 }
]
}The variant that a rollout serves has the reason SPLIT.
Weights
Weights are relative. Toggld divides each weight by the sum of all weights:
| Splits | Result |
|---|---|
on: 20, off: 80 | 20% on, 80% off |
on: 1, off: 1 | 50% on, 50% off |
a: 1, b: 1, c: 2 | 25% a, 25% b, 50% c |
Rules for weights:
- Each weight must be a finite number that is zero or greater.
- At least one weight must be greater than zero.
- Every split must name a variant that exists in the environment.
Toggld assigns users to one of 10,000 buckets, so the smallest useful step is 0.01%.
Sticky bucketing
Toggld computes each user's bucket from a hash. It uses MurmurHash3 (32-bit) over the text flagKey:ruleId:subject, then takes the result modulo 10,000. The subject is the value of the bucketing attribute, which is targetingKey by default.
The splits divide the 10,000 buckets into ranges in the order that they appear. A user receives the variant whose range contains their bucket.
This design has these results:
- The same user, flag, and rule always produce the same bucket, on every server and in every SDK mode.
- Different flags and different rules produce independent buckets. A user in the first 20% of one flag is not more likely to be in the first 20% of another.
- No state is stored. Toggld does not remember assignments.
What changes assignments
| Change | Effect |
|---|---|
| Raise or lower a weight in a two-split rollout | Only users near the boundary move. Users who already have the growing variant keep it. |
| Change weights in a rollout with three or more splits | Users can move between other variants when a middle range shifts. |
| Reorder the splits | Most users can change variant. |
Change the rule id, the flag key, or bucketBy | Every user gets a new bucket. |
Change a user's targetingKey | That user gets a new bucket. |
The dashboard creates rule IDs for you. If you write rules through the API, keep each rule's id stable.
Bucket by another attribute
Set bucketBy to bucket by a different context attribute. For example, bucket by companyId so that every user in a company gets the same variant:
{ "type": "rollout", "bucketBy": "companyId", "splits": [{ "variant": "on", "weight": 10 }, { "variant": "off", "weight": 90 }] }The attribute value must be a string. A number does not count.
Missing bucketing key
If the context has no usable value for the bucketing attribute, the rollout cannot choose a bucket. Evaluation stops at that rule with the error code TARGETING_KEY_MISSING. Toggld does not try the rules below it. Your code receives its fallback value.
targetingKeymust be a non-empty string.- A custom
bucketByattribute must be a string.
To serve anonymous users, give them a stable ID, such as a random ID stored in a cookie or in local storage. Or add a rule above the rollout that matches users without the attribute (notExists) and serves a fixed variant.
Roll out safely
- Create and test the rollout in Development before you change Production.
- Make sure that your fallback value in code is safe.
- Start with a small percentage.
- Save, wait for the success message, then confirm that your application receives the expected values.
- Check the flag's Evaluations panel for the variant mix and errors. See Analytics.
- Increase the percentage in steps. Raise the weight of the new variant without reordering the splits.
- When the rollout reaches 100%, plan to retire the flag.
If something goes wrong, turn the flag off. Toggld then serves the off variant to everyone. Changes take time to reach every SDK. See how fast changes arrive.