Configure conditional flag delivery with targeting rules, conditions, operators, and gradual rollouts
Last updated November 21, 2026
Targeting Rules
Targeting rules let you control exactly who sees a feature flag based on evaluation context properties. Rules are evaluated server-side and support complex conditions, nested groups, and gradual rollouts.
How Evaluation Works
When a flag is evaluated, Flaggr follows this sequence:
- Disabled check — if the flag is disabled, return the default value with reason
DISABLED - Overrides — identity-based value overrides bypass all rules
- Prerequisites — all prerequisite flags must match expected values
- Targeting rules — evaluate each rule's conditions against the context (with schedule gating)
- Variant selection — if no rule matches, check variants with percentage-based rollout
- Default value — if nothing matches, return the default with reason
DEFAULT
Evaluation Context
Every evaluation can include a context object describing the request:
{
"context": {
"targetingKey": "user-123", // Required for consistent rollouts
"email": "alice@example.com",
"plan": "enterprise",
"country": "AU",
"betaUser": true,
"signupDate": "2025-06-15"
}
}The targetingKey is critical — it's used for consistent hashing in percentage rollouts, ensuring the same user always gets the same variant.
Rule Structure
Each targeting rule contains conditions and an action:
{
"targeting": [
{
"id": "enterprise-users",
"conditions": [
{ "property": "plan", "operator": "in", "value": ["enterprise", "business"] },
{ "property": "country", "operator": "equals", "value": "AU" }
],
"conditionOperator": "and",
"value": true
}
]
}When a rule matches, the flag returns the rule's value (the flag's default value when the rule has none), labelled with the rule's variant if it names one, with reason TARGETING_MATCH. A rule with condition groups matches through its groups, otherwise through its conditions, and a rule with neither matches everyone. Not every evaluator does that yet: see Evaluation Order.
A rule that serves everyone leaves everything after it unreachable: the rules below it, the variant split and the default value. Such a rule matches everyone (no condition groups, and no conditions or only the match-all condition described under Evaluation Order), has no schedule, and has no rolloutPercentage or 100. The console marks what it makes unreachable, and rollout plans and canaries don't start behind such a rule (409 ROLLOUT_RULE_SHADOWED).
Condition Operators
| Operator | Description | Value Type | Example |
|---|---|---|---|
equals | Exact match | string | number | boolean | {"property": "plan", "operator": "equals", "value": "enterprise"} |
not_equals | Not equal | string | number | boolean | {"property": "status", "operator": "not_equals", "value": "banned"} |
in | Value in list | Array | {"property": "country", "operator": "in", "value": ["AU", "NZ", "US"]} |
not_in | Value not in list | Array | {"property": "plan", "operator": "not_in", "value": ["free", "trial"]} |
contains | String contains | string | {"property": "email", "operator": "contains", "value": "@acme.com"} |
starts_with | String prefix | string | {"property": "email", "operator": "starts_with", "value": "admin"} |
ends_with | String suffix | string | {"property": "email", "operator": "ends_with", "value": ".gov.au"} |
regex | Regex match | string (pattern) | {"property": "email", "operator": "regex", "value": "^.*@(acme|corp)\\.com$"} |
greater_than | Numeric > | number | {"property": "age", "operator": "greater_than", "value": 18} |
less_than | Numeric < | number | {"property": "age", "operator": "less_than", "value": 65} |
gte | Numeric >= | number | {"property": "version", "operator": "gte", "value": 2} |
lte | Numeric <= | number | {"property": "version", "operator": "lte", "value": 5} |
before | Date before | string (ISO date) | {"property": "signupDate", "operator": "before", "value": "2025-01-01"} |
after | Date after | string (ISO date) | {"property": "signupDate", "operator": "after", "value": "2024-06-01"} |
in_cohort | Member of cohort | boolean + cohortId | {"property": "targetingKey", "operator": "in_cohort", "value": true, "cohortId": "cohort-beta"} |
not_in_cohort | Not in cohort | boolean + cohortId | {"property": "targetingKey", "operator": "not_in_cohort", "value": true, "cohortId": "cohort-internal"} |
Condition Groups
For complex logic, use condition groups with nested AND/OR operators:
{
"targeting": [
{
"id": "complex-rule",
"groups": [
{
"conditions": [
{ "property": "plan", "operator": "equals", "value": "enterprise" },
{ "property": "country", "operator": "in", "value": ["AU", "NZ"] }
]
},
{
"conditions": [
{ "property": "betaUser", "operator": "equals", "value": true }
]
}
],
"groupOperator": "or",
"value": true
}
]
}This reads as: Enterprise users in AU/NZ, OR any beta user.
Within each group, every condition must match (AND): a group has no operator of its own, and a group without conditions matches nobody. Groups are combined with groupOperator (default or). When a rule has groups, its flat conditions are ignored.
Gradual Rollouts
Use rolloutPercentage to gradually expose a feature to a percentage of users:
{
"targeting": [
{
"id": "canary-rollout",
"conditions": [
{ "property": "plan", "operator": "not_equals", "value": "free" }
],
"rolloutPercentage": 25,
"value": true
}
]
}This enables the feature for 25% of paying users. The percentage is determined by consistent hashing on flagKey + ":rollout:" + targetingKey, so each user consistently gets the same result across evaluations. Without a targetingKey, a rule with a percentage below 100 never includes the user. The exception is the @flaggr/sdk 0.4.0 script-tag bundle (sdk.js) evaluating locally (with updateMode: 'stream', bootstrap or remoteConfig): it puts every context without one in the same bucket, so such a rule includes all of them or none. 0.5.0 and later leave them out like the servers.
rolloutPercentage is a whole number from 0 to 100, as are variant weights: the API refuses others (400). The data plane can't load a fractional or negative one: stored, it would make https://api.flaggr.dev answer 503 for every flag of that service and environment.
The data plane sends an unset rolloutPercentage as null (in /api/flags/export and its streams). The 0.4.0 script-tag bundle evaluating locally skips a rule whose percentage is null and goes on to the next rule. It meets one only in a bootstrap built from the data plane's flags, such as that export: it can't stream from https://api.flaggr.dev, and remoteConfig gets the rules as stored, without the field. 0.5.0 serves such a rule.
How Consistent Hashing Works
Flaggr uses a 32-bit string hash (multiply by 31 and add each character's code point, see Advanced Evaluation):
- Builds the hash input
flagKey + ":rollout:" + targetingKey - Computes a 32-bit integer hash and takes its absolute value
- Takes
hash % 100to get a value 0–99 - If the value is less than
rolloutPercentage, the user is included
This guarantees that user abc always gets the same outcome for flag checkout-v2, regardless of when or where the evaluation happens.
Variants
Variants allow A/B testing and multi-way splits with weighted distribution:
{
"variants": [
{ "name": "control", "value": "classic-checkout", "weight": 50 },
{ "name": "treatment-a", "value": "new-checkout", "weight": 30 },
{ "name": "treatment-b", "value": "express-checkout", "weight": 20 }
]
}Variant weights should sum to 100: a user whose bucket is past the last weight gets the first variant. The variant assigned to a user is determined by the same hash, of flagKey + targetingKey, ensuring stable assignment.
When a variant is selected, the response includes:
{
"value": "new-checkout",
"variant": "treatment-a",
"reason": "VARIANT"
}Targeting Rules with Variants
A rule can name a variant, which the response then reports. The rule still serves its own value (the flag's default value when it has none), not the variant's, so give it the variant's value too:
{
"targeting": [
{
"id": "force-enterprise-to-treatment",
"conditions": [
{ "property": "plan", "operator": "equals", "value": "enterprise" }
],
"variant": "treatment-a",
"value": "new-checkout"
}
]
}The console's Return Variant and MCP add_targeting_rule with variant write the variant's value for you, and refuse a name the flag's variants don't have.
Evaluation Reasons
Every evaluation response includes a reason field:
| Reason | Description |
|---|---|
DISABLED | Flag is disabled, returned default value |
OVERRIDE | An identity override matched |
PREREQUISITE_FAILED | A prerequisite flag didn't match |
TARGETING_MATCH | A targeting rule's conditions matched |
VARIANT | Matched via variant percentage distribution |
DEFAULT | No rule matched, returned default value |
NOT_FOUND | Flag key doesn't exist |
ERROR | Evaluation error occurred |
CACHED | Returned from cache |
STATIC | Static/hardcoded value |
Evaluation Order
Rules are evaluated top-to-bottom. The first matching rule wins. Design your rules with the most specific conditions first:
{
"targeting": [
{ "id": "block-banned", "conditions": [{"property": "banned", "operator": "equals", "value": true}], "value": false },
{ "id": "enterprise-early", "conditions": [{"property": "plan", "operator": "equals", "value": "enterprise"}], "value": true },
{ "id": "gradual-rollout", "conditions": [{"property": "targetingKey", "operator": "not_equals", "value": "__flaggr_rollout_match_all__"}], "rolloutPercentage": 10, "value": true }
]
}- Banned users are always excluded
- Enterprise users always get the feature
- Everyone else gets a 10% gradual rollout
A rule with no conditions (an empty conditions array and no groups) matches everyone, so the third rule could leave its conditions empty. https://flaggr.dev evaluates rules that way, and so does @flaggr/sdk evaluating locally from 0.5.0, but a data plane from before Flaggr 0.5.0 and local evaluation before 0.5.0 match a rule with no conditions to nobody, so the third rule uses a condition every user meets, which works on every version: a real targetingKey never equals __flaggr_rollout_match_all__, and a context without one doesn't either. Rollout plans write the same condition when a stage is open to everyone, and the console shows it as Everyone.
Best Practices
- Always include
targetingKeyin your evaluation context for consistent rollouts - Order rules from most to least specific — first match wins
- Use condition groups for complex logic instead of duplicating rules
- Start rollouts small (5–10%) and increase gradually
- Use
regexsparingly — it's powerful but harder to debug - Test with the evaluation API before relying on client-side SDKs
Related
- Cohorts — Reusable audience segments for targeting
- Progressive Rollouts — Staged deployment with safety checks
- Overrides & Prerequisites — Identity overrides and flag dependencies
- Scheduled Rules — Time-based rule activation
- REST Evaluation API — Evaluate flags via HTTP
- Protocols — Connect-RPC, gRPC, and OFREP evaluation
- Environments — Per-environment targeting