Targeting and rollouts
Every flag is decided per person and per environment, in a fixed order, so the same person always gets the same answer.
The order of decisions#
The first step that applies decides the result:
- Emergency stop. Serves the off result to everyone (
KILL_SWITCH). - Flag off. The environment's switch is off (
DISABLED). - Explicit targeting. Listed users, accounts and devices get the flag on (
TARGETED_USER). - Segments. Members of a targeted segment get it on (
SEGMENT_MATCH). - Rules. A matching attribute rule turns it on (
RULE_MATCH). - Prerequisites and rollout. Prerequisite flags gate the percentage rollout; then the rollout decides (
DEPENDENCY_BLOCKED,ROLLOUT_IN,ROLLOUT_OUT,FULL_ROLLOUT).
Percentage rollouts#
A rollout hashes a stable identifier together with the flag key, so a person stays on the same side as you raise the percentage: anyone in at 10% is still in at 50%. By default the rollout buckets by user. A flag can instead bucket by account, so a whole organization gets a feature together, or by device.
Missing identifiers do not fall back
NO_IDENTIFIER rather than being assigned by a different identifier. That keeps results explainable.Variants#
A flag can be a boolean, string, number or JSON. Non-boolean flags have two to twenty typed variants. In each environment you choose which variant is served when the flag is off and how the traffic splits between variants (the weights add up to 100). The variant is chosen by its own hash, independent of the on/off rollout.
Segments#
A segment is a reusable audience. It belongs to the whole organization by default, so flags in any project can use it, or you can scope it to one project when you create it, so only that project's flags can (the scope cannot be changed later): explicit users, accounts and devices, attribute rules, and other segments it includes. Attribute rules support equals, contains and in. Segments can include each other up to four levels deep; a looping segment matches nobody, and a segment that does not exist matches only people whose SDK user lists its key.
SDK users can also carry segment keys themselves (segments: ["beta"] on the user). They count as extra membership for any flag that names that segment, and cannot override the kill switch or a disabled flag. Keys sent with a client key are trusted client input that any browser can fake: use them for convenience and personalisation, not security gating. With a server key your backend is authoritative.
- A segment cannot be deleted while a flag or another segment uses it.
- An organization-wide segment can include only organization-wide segments; a project segment can also include segments of the same project.
- A flag can use organization-wide segments and segments scoped to its own project; a segment scoped to another project is refused.
- Roles that cannot change production targeting cannot edit a segment used by a production flag.
- Segment contents are audited but not versioned per flag.
Prerequisites#
A flag can require other flags of the same project and environment to be on for the same person. Prerequisites gate only the percentage rollout, so people who are explicitly targeted, in a matching segment or matching a rule are not blocked. A missing, archived, looping or too deep prerequisite fails closed. Chains can be up to five flags deep and ten per flag.
History and instant rollback#
Every change writes an immutable version per environment. Rolling back applies an old snapshot as a new version, so history is never rewritten. Rollback never restores the emergency stop and is refused while it is active. You can roll back in the console or with an admin key through the API.
POST /api/v1/flags/{flagKey}/environments/{environment}/rollback