Advanced
How decisions are made
Evaluation order, bucketing, hashing and the rules for porting an SDK.
A decision is a pure function of the datafile and the user: no network, no clock, no randomness, no stored state. The same inputs give the same variation on the website, in the app and on the server. This page is the specification every SDK implements.
Evaluation order#
| Step | Result | Reason |
|---|---|---|
| 1. The flag isn't in the datafile | disabled, no variation, no variables | FLAG_NOT_FOUND |
| 2. The flag is switched off | the off variation | FLAG_DISABLED |
| 3. The user id has an override (to an existing variation) | that variation | OVERRIDE |
| 4. Rules, top to bottom: the first whose conditions match and whose traffic includes the user, and whose variation pick lands on an existing variation | that variation | RULE_MATCH |
| 5. Nothing took the user | the default variation, else the off variation | DEFAULT |
A preview (client.setPreview({ flag: "variation" })) comes before all of this: the flag decides that variation, even when it's switched off, with the reason PREVIEW, and the client sends no events while it's on.
Before a datafile is available the SDK answers NOT_READY without evaluating anything. inExperiment is true only for step 4 with an experiment rule; that's when an exposure is logged. enabled is the chosen variation's enabled, and variables are the variation's values over the flag's defaults.
Bucketing#
Users are placed in one of 10,000 buckets with MurmurHash3 (32-bit, seed 1) over the UTF-8 bytes of a key:
bucket(key) = floor(murmurhash3_32(utf8(key), seed = 1) * 10000 / 2^32) // 0 … 9999
id = user.bucketingId ?? user.id
inRule = bucket(`${rule.salt}:traffic:${id}`) < rule.traffic
variation = first allocation where bucket(`${rule.salt}:variation:${id}`) < cumulative weight- Traffic and variation use independent keys. Raising a rule's traffic from 10% to 50% adds users; nobody already in moves to another variation.
- The salt is fixed per rule, generated by the server when the rule is created. Renaming or editing a rule never reshuffles users; two rules (or two flags) bucket independently.
bucketingIdlets a group share a variation: pass a company id and everyone in the account sees the same thing. Overrides still useuser.id.- If the weights add up to less than 10,000 and the user lands in the gap, the rule is skipped and evaluation continues with the next rule.
Conditions#
Conditions are type-strict, a missing attribute makes every operator false except exists, unknown audiences, locations and operators are false, and audience references are followed at most 32 levels deep. The full semantics are in Targeting and audiences; URL matching for locations is in Locations.
Porting to another platform#
Every SDK (JavaScript, React Native, Node.js, Python, Go, Java, PHP, Ruby, .NET, Swift, Kotlin and Flutter) is tested against the same vectors in packages/core/test-vectors/, and a new port is correct only if it reproduces them too:
| File | Contents |
|---|---|
hash.json | MurmurHash3 inputs and outputs (the first five are the published reference values). |
bucket.json | Keys and their bucket numbers. |
datafile.json | A datafile covering every rule and condition feature. |
decisions.json | Users and the exact decision each must get from datafile.json. |
Checklist#
- Hash the UTF-8 bytes, not UTF-16 code units: non-ASCII ids (
ğüşıöç) must give the same bucket everywhere. - Use unsigned 32-bit arithmetic and integer division for the bucket.
- Compare attribute values type-strictly; don't coerce numbers and strings.
- Never go back to an older datafile revision.
- Deduplicate exposures per user, flag, rule and variation, and give every event a unique
uuid. - Never send
pageoractiveLocationswith events.