Feature flags
A feature flag lets you run an A/B test and roll a change out in stages. It controls which visitors see a change to your site, and you deploy no code.
Keys
Each feature flag has a unique key. Your application uses this key to check whether Picked allocates a visitor to the feature flag. You set the key when you create the feature flag, and you cannot change it later.
Types
Each feature flag has a type. You set the type when you create the feature flag, and you cannot change it later.
| Type | What your site receives | Groups |
|---|---|---|
| Boolean | true or false | Two |
| Text | A string that you write, or false for the control group | Two or more |
Choose Boolean for one change against no change. Choose Text when you must test several changes at the same time, and each change needs its own group.
Set the allocation
Set the allocation from the detail page of the feature flag:
| Control | What it does |
|---|---|
| Enabled | Whether Picked allocates a visitor to the feature flag. A disabled feature flag allocates nobody, and it records nothing. See Disable a feature flag. |
| Weight | The percentage of visitors that Picked allocates to a Boolean feature flag, from 0 to 100. |
| Variants | The groups of a Text feature flag, and the traffic that each one receives. See Variants. |
| Description | An internal note about what the feature flag tests. |
A Boolean feature flag has one weight. For each visitor it gives one of two outcomes: allocated, or not allocated. A weight of 30 allocates 30% of your visitors. The other 70% stay unallocated. A weight of 0 allocates nobody. A weight of 100 allocates everybody.
Variants
A Text feature flag has a table of variants. Each row is one group of visitors:
| Column | What it does |
|---|---|
| Name | A label for the variant. It appears in your reports. You can change it at any time. |
| Value | The string that your site receives for a visitor in this variant. |
| Weight | The share of traffic for this variant, against the other rows. |
The first row is Control. Picked always sends false to a visitor in the control
group, and you cannot remove the row, move it, or change its value. It takes a weight like
any other row.
The weights are shares, and not percentages. Picked reduces them to their smallest whole
numbers, so 10 : 10 : 20 and 1 : 1 : 2 are the same split. The percentage beside each
row shows the traffic that the variant receives.
Choose Even split to give every variant the same weight.
How Picked allocates a visitor
The allocation is deterministic. It derives from the visitor ID and from the ID of the feature flag. A Boolean feature flag then compares that value against the weight, and a Text feature flag compares it against the range of each variant. Each feature flag gets its own value, so tests that run at the same time are independent. See About feature flag allocation.
Disable a feature flag
A disabled feature flag allocates nobody, and it records nothing. The difference from a weight of 0 matters for your reports. The visitor is not in the test at all, and the visitor is not in the control group.
The SDK does not evaluate a disabled feature flag. It stores no decision in the browser of the visitor, and it reports no decision to your analytics. Such a feature flag is absent from the feature list on every analytics event.
An experience whose condition points at a disabled feature flag behaves as though the visitor is not in the test. The condition reads as not allocated, and Picked records no assignment.
This state is temporary, and it discards no decision that Picked made already. A visitor who was allocated before keeps that decision in the browser. When you enable the feature flag again, Picked continues from that decision, and the visitor stays in the group they were already in.
A disabled feature flag stays visible in the developer tools, and a URL override still turns one on for QA.
Feature flag versions
Each feature flag has a version number, and it starts at 1. The SDK caches an allocation decision in the browser of the visitor under a key, and the version is part of that key. The version does nothing else, and it is not an input to the allocation value. When you increment the version, the SDK discards those cached decisions. It then evaluates every visitor again on the next page load.
What happens when you increment the version
- The SDK invalidates the cached decisions. The cache key holds the version, so the old entry no longer matches and the feature flag counts as undecided.
- Picked evaluates each visitor against the current weight. The allocation is deterministic and the version is not one of its inputs, so the same visitor against an unchanged weight gives the same result.
- You cannot reverse this. There is no way to decrement a version.
When to increment
Increment the version after you change the weight. Do this when you want Picked to evaluate an allocated visitor again against the new weight, and not to use the cached decision.
When not to increment
To apply a weight change only to a visitor that Picked does not allocate yet, change the weight and leave the version as it is. An allocated visitor keeps the current allocation.