Percentage Rollouts

How to use percentage rollouts with feature flags.

Per­cent­age roll­outs let you grad­u­al­ly enable a flag for a por­tion of your audi­ence. Set a roll­out per­cent­age (1 – 100) on a flag, and users are deter­min­is­ti­cal­ly buck­et­ed so they see a con­sis­tent experience.

How It Works #

When a flag has a roll­out per­cent­age and no tar­get­ing rule has matched, the plu­g­in com­putes a buck­et (0 – 99) from a hash of the user’s iden­ti­fi­er and the flag handle:

bucket = abs(crc32(userId + ':' + flagHandle)) % 100

If the buck­et val­ue is less than the roll­out per­cent­age, the flag is enabled for that user.

Impor­tant Info

  • The same user always gets the same buck­et for a giv­en flag. No flip-flop­ping between visits.
  • Going from 25% to 50% adds users. Nobody who had the fea­ture los­es it.
  • The flag han­dle is part of the hash, so a user gets dif­fer­ent buck­ets for dif­fer­ent flags. The same users aren’t always the first to get new features.
  • No data­base table track­ing who’s in which cohort. The buck­et is com­put­ed on the fly.

Buck­et Input Pri­or­i­ty #

The plu­g­in deter­mines the buck­et input in this order:

  1. Explic­it bucketKey — if passed to isEnabled(), used directly
  2. User ID — if the user is logged in
  3. Anony­mous vis­i­tor cook­ie — a UUID stored in a first-par­ty cook­ie (_ff_vid by default)

If none of these are avail­able (e.g., a con­sole request with no user and no cook­ie), the roll­out check is skipped and the flag returns false.

Anony­mous Vis­i­tors #

For logged-out vis­i­tors, the plu­g­in gen­er­ates a UUID and stores it in a first-par­ty cook­ie. This ensures the same vis­i­tor sees the same flag state across page views and return visits.

The cook­ie is con­fig­ured in plu­g­in set­tings or in a con­fig file:

  • Cook­ie name: _ff_vid (con­fig­urable via anonymousCookieName
  • TTL: 1 year (con­fig­urable via anonymousCookieTtl)
  • Attrib­ut­es: httpOnly, secure (on HTTPS), sameSite=Lax, path=/

Set anonymousCookieTtl to 0 to dis­able cook­ie-based buck­et­ing. Per­cent­age roll­outs will then only work for logged-in users.

Grad­ual Ramp-Up Strat­e­gy #

A typ­i­cal roll­out progression:

  1. 1% — smoke test with a tiny slice of real traffic
  2. 10% — val­i­date met­rics and watch for errors
  3. 25% — broad­er expo­sure, con­firm per­for­mance at scale
  4. 50% — half your audi­ence, mon­i­tor for a day or two
  5. 100% — full roll­out, then clean up the flag

Each increase adds users with­out reshuf­fling exist­ing ones.

Com­bin­ing Rules and Roll­outs #

Tar­get­ing rules and per­cent­age roll­outs work together:

  1. Rules are eval­u­at­ed first. If any rule match­es, the flag is enabled immediately
  2. If no rules match, the per­cent­age roll­out is checked
  3. If nei­ther match­es, the flag returns false

This lets you do things like: ​“Enable for all inter­nal staff (via user group rule) AND roll out to 10% of every­one else (via percentage).”