Targeting rules
Decide who gets what: specific people with targets, groups with rules, and everyone else with the fallthrough. Rules read whatever attributes you pass in the context.
Contexts
The context is the second argument to get(). key identifies it; everything else is an attribute rules can match on.
flags.get("new-checkout", { key: "usr_123", plan: "pro", country: "DE", appVersion: "4.3.1" }, false);
A plain object is a user. When one decision depends on several things at once, a user, their
organization and their device, pass a multi-context:
flags.get("new-checkout", {
kind: "multi",
user: { key: "usr_123", plan: "pro" },
organization: { key: "org_9", tier: "enterprise" },
device: { key: "dev_abc", os: "ios", osVersion: "17.2" },
}, false);
Every clause names a contextKind (default user). A clause about a kind the context
doesn't have doesn't match. Attributes can be nested: address.country reads
{ address: { country } }. kind is reserved and never matches.
Targets: specific keys
Listed keys get their variation before any rule runs. Use it for staff, QA accounts, or one customer who asked.
"targets": [
{ "variation": 1, "keys": ["u-ana", "u-ben", "qa-bot"] }
]
Up to 10,000 keys per target. Longer lists belong in a segment.
Rules: groups
A rule is a list of clauses and what to serve when they all match. Rules are checked in order and the first match wins.
"rules": [
{
"description": "paid plans on 4.2 or later",
"clauses": [
{ "attribute": "plan", "op": "in", "values": ["pro", "team"] },
{ "attribute": "appVersion", "op": "semVerGreaterThan", "values": ["4.2.0"] }
],
"variation": 1
},
{
"description": "10% of the Netherlands",
"clauses": [{ "attribute": "country", "op": "in", "values": ["NL"] }],
"rollout": { "variations": [{ "variation": 1, "weight": 10000 }, { "variation": 0, "weight": 90000 }] }
}
]
- Clauses in a rule are ANDed. For OR, write two rules.
- A clause matches if the attribute matches any value in
values. - A rule serves either a
variationor arollout, never both. - Up to 200 rules, 50 clauses each, 1,000 values per clause.
There's no nested AND/OR tree on purpose: anything more complex reads better as a segment.
Operators
| Operator | Matches when the attribute… |
|---|---|
in | equals one of the values. Strict: "42" doesn't match 42. |
startsWith, endsWith, contains | is a string that starts with, ends with or contains a value. |
matches | matches a regular expression (unanchored). Patterns that could hang the evaluator are refused when you save them. |
lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual | is a finite number compared with a value. |
before, after | is a date (ISO 8601 or epoch ms) before or after a value. |
semVerEqual, semVerLessThan, semVerGreaterThan | is a version, compared by semver rules. "17.2" counts as 17.2.0. |
segmentMatch | belongs to one of the segments named in values. |
Three rules make operators safe in a request path:
- A type mismatch is no match. Never a coercion, never an exception.
- Array attributes match if any element matches.
groups: ["a", "b"]isin ["b"]. - An unknown operator is no match, so an older SDK reading a newer rule degrades instead of failing.
Negation
"negate": true inverts a clause, so country in ["US"] becomes "not in the US". A
context missing the attribute counts as "not in", the way you'd expect.
If a segment can't be read (a corrupt or unknown snapshot format), a negated clause would otherwise become true for everyone, and "everyone except enterprise" would include enterprise. Instead, a rule with an unreadable segment never matches, in either polarity. Evaluation moves on to the next rule.
Prerequisites
A prerequisite makes one flag depend on another: new-checkout only serves its rules if payments-v2 is on and serving variation 1.
"prerequisites": [{ "flagKey": "payments-v2", "variation": 1 }]
An off prerequisite always fails, whatever its off variation is, so the kill switch on
payments-v2 also turns off everything gated behind it. A failed prerequisite serves the off
variation with PREREQUISITE_FAILED. Cycles are refused when the snapshot compiles.
What you get back
detail() tells you why a value was served:
flags.detail("new-checkout", { key: "usr_123", plan: "pro" }, false);
// { value: true, variationIndex: 1, reason: { kind: "RULE_MATCH", … } }
Every variation is checked against the flag's kind before it's served. A boolean flag never
hands your if a string; a mismatch returns your default with ERROR.
Changing targeting
curl -X PATCH https://flags.acme.com/v1/admin/projects/acme/environments/production/flags/new-checkout \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" -H "Content-Type: application/json" \
-d '{
"expectedVersion": 413,
"rules": [{ "clauses": [{ "attribute": "plan", "op": "in", "values": ["pro"] }], "variation": 1 }]
}'
You: Only give new-checkout to Pro customers in production.
rules is replaced as a whole list, so read the current configuration, edit it and send it back with
its version. See the API.