Target by person, account, device and attribute
Tell FlagSwift who a person is, then choose the flag's audience by listing identifiers or by matching attributes.
- Time
- About 10 min
- Who can do it
- Product manager, Developer, Release manager or Admin. In production only a Release manager or an Admin.
- Where
- Flags > your flag > Targeting & rollout
- You finish with
- People and attribute rules that decide who gets the flag
What and why#
What it is#
Targeting decides who gets a flag before any percentage is applied. You can name people, accounts or devices directly, or describe them with attribute rules such as plan equals pro. FlagSwift never looks anything up about a person: it only knows what each evaluation request carries, so what you send is what you can match on.
When to use it#
- Give a named group early access: your own team, a design partner, a customer who asked for the feature.
- Open a feature to everyone on a plan or in a country without a deploy, with a rule such as
plan equals pro. - Test in production with a handful of identifiers before any rollout percentage is raised.
How it works#
On every evaluation the engine goes through the checks listed under The order the steps are checked below and stops at the first one that decides. A listed person or a matching rule serves the flag on straight away, so they are never counted by the rollout percentage. Everyone else falls through to the rollout.
Before you start#
- The
targeting.updatepermission in the environment. Product managers, Developers, Release managers and Admins have it outside production. In production Developers and Product managers are read-only, so a Release manager or an Admin makes the change. See Give people the right access. - A flag with an environment you can edit. If the environment requires approval, targeting changes are refused with
APPROVAL_REQUIREDand go through a release instead. See Put production behind review. - An SDK or API call that sends the identifiers and attributes you want to match on. FlagSwift only knows what each request tells it. Pick an SDK in Choose and set up an SDK.
- The flag switched on in the environment. A flag that is off ignores every list, segment and rule: the reason is
DISABLED.
Describe the person#
Every evaluation can carry up to four kinds of information. Send only what your rules use.
| Field | Type | Description |
|---|---|---|
| identifiers | string[] | The user. Up to 10 values. The first one is what a rollout counts when the flag rolls out by user. |
| accounts | string[] | The company, workspace or tenant the person acts for. Up to 10 values. |
| devices | string[] | The browser, install or device. Up to 10 values. |
| attributes | object | Free-form values such as plan or country. Up to 8 KB once written as JSON. |
curl -s -X POST "https://flags.example.com/api/v1/evaluation/client?env=production" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"identifiers":["user-123"],"accounts":["acme"],"devices":["ios-8f2c"],"attributes":{"plan":"pro","country":"NG"}}'A server key can also use GET with user_identifier, account_identifier, device_identifier and user_attributes (JSON) in the query. Attributes that are too large or not a JSON object are refused with INVALID_ATTRIBUTES. See the Evaluation API.
Walk through it#
Open the targeting settings
Open Flags, choose the flag and open the Targeting & rollout tab. Pick the environment at the top. The badge next to it reads On, Off or Kill switch. The page lists numbered steps in the order they are checked: Always on for, Segments, Rules, Prerequisites and Everyone else: rollout, then Variants for a flag that has them.
List people, accounts or devices
In step 1, Always on for, switch on Always on for these people. Choose Users, Accounts or Devices and enter one value per line. Each tab shows a count of its entries. Anyone listed gets the flag on, whatever the rollout says.
Step 1, Always on for. The Users tab shows how many entries it holds, and the list takes one value per line. - Each list holds up to 1,000 entries. Blank lines and duplicates are dropped and each entry is trimmed.
- Matching is exact and case-sensitive.
User-123does not matchuser-123. - A match on any of the three lists is enough, and each list is checked against the matching field of the request.
- Switching the toggle off keeps your entries but ignores them until you switch it on again.
A switched-off flag ignores the lists
The flag's own on/off switch comes first. Listing a person does not turn on a flag that is off in the environment, and an active kill switch overrides everything.Add an attribute rule
In step 3, Rules, choose Add rule. Each condition has an attribute name, an operator and a value. The attribute name must match the key you send, for example
plan. Use And condition to add another condition to the same rule, and Add rule again to add an alternative (shown as Or rule 2).Step 3, Rules, with a tester open. The tester ticks each condition that holds and says which rule matched. Nothing is saved by testing. Operators Operator Description equals Exact match, with capital letters counted. prodoes not matchPro. Numbers and booleans are compared as text, so5matches"5"andtruematches"true".contains Text that includes the value, or a list attribute that holds the value as one of its items. is one of (in) Matches when the attribute equals any value in your list. Type a value and press Enter or a comma, or paste several separated by commas or lines. All conditions in one rule must match. The flag is served when any rule matches. A rule with no conditions never matches, so an empty rule cannot turn the flag on for everyone.
A missing attribute never matches
If the request does not carry the attribute, or sends it as null, the condition is false. Send the attribute on every request that should be considered.Try the rules before you save
Choose Test these rules under the rules. It fills in a JSON object with your attribute names. Enter the values of a sample person and read the result: it says which rule matches, or
No rule matches this person., and ticks or crosses each condition. An attribute you left out is marked(attribute not provided). Nothing is saved by testing.You should see. For{ "plan": "pro" }against the ruleplan equals pro, you seeMatches rule 1: this person would be served the flag.Choose what the rollout counts
In step 5, next to Roll out by, choose User, Account or Device. Everyone else falls through to the percentage and is counted by that kind of identifier. If the request lacks it, the person gets the off result with
NO_IDENTIFIER. Changing this needs the rollout permission, which Product managers do not have. See Roll out a feature.Save and check
Choose Save changes. It stays off while a rule is incomplete: the editor names the problem, such as an empty attribute or value, and the error appears under the Rules step. Then open Check who gets this flag and test a listed person.
The check box at the bottom of the tab. It uses the saved settings, so save first. The result shows the reason code beside Served or Not served. You should see. The result reads Served with the reasonTARGETED_USERfor a listed person, orRULE_MATCHfor a person who matches a rule.
The order the steps are checked#
The first step that decides serves the result, so a person who matches an earlier step never reaches a later one.
| Check | Description |
|---|---|
| 1. Kill switch | Off for everyone, reason KILL_SWITCH. |
| 2. Flag switched off | Off, reason DISABLED. Targeting does not override it. |
| 3. Always on for | On, reason TARGETED_USER, when the toggle is on and a user, account or device is listed. |
| 4. Segments | On, reason SEGMENT_MATCH. |
| 5. Rules | On, reason RULE_MATCH. |
| 6. Prerequisites | If a prerequisite flag is not on for the person, the rollout is skipped with DEPENDENCY_BLOCKED. People matched in steps 3 to 5 are not held back. |
| 7. Rollout | FULL_ROLLOUT at 100, ROLLOUT_IN or ROLLOUT_OUT in between, NO_IDENTIFIER when the identifier is missing. |
Limits#
| Limit | Description |
|---|---|
| List entries | 1,000 each of users, accounts and devices per environment. |
| Rules | 20 per environment, each with at most 10 conditions. |
| Attribute name | Up to 100 characters: letters, numbers and . _ : -. |
| Condition value | Up to 255 characters. An is-one-of list holds at most 100 values. |
| Segments | A flag environment can use at most 20 segments. |
| Evaluation request | Up to 10 identifiers of each kind and 8 KB of attributes. |
Do it with the API#
These are Dashboard API calls, which authenticate with your signed-in session cookie (auth_session), not an API key. Replace FLAG_ID with the flag's id and staging with the environment key. You need flags.update, plus targeting.update in that environment.
Replace the lists and rules of one environment
Send only what you want to change. rules and the lists replace what is there, they are not merged. Each save becomes a new version.
curl -s -X PATCH "https://flags.example.com/api/flags/$FLAG_ID/environments/staging" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"targeting": { "enabled": true, "users": ["user-123"], "accounts": ["acme"], "devices": [] },
"rules": [
{ "id": "pro-in-ng", "conditions": [
{ "attribute": "plan", "operator": "equals", "value": "pro" },
{ "attribute": "country", "operator": "in", "value": ["NG", "GH"] }
] }
]
}'{
"status": "success",
"message": "Environment updated successfully",
"data": {
"id": "6650c1f2a9b3d4e5f6a7b8c9",
"name": "new-dashboard",
"environments": {
"staging": {
"enabled": true,
"rolloutPercentage": 0,
"targeting": { "enabled": true, "users": ["user-123"], "accounts": ["acme"], "devices": [] },
"rules": [{ "id": "pro-in-ng", "conditions": [
{ "attribute": "plan", "operator": "equals", "value": "pro" },
{ "attribute": "country", "operator": "in", "value": ["NG", "GH"] }
] }],
"version": 8
}
}
}
}Check a person without changing anything
The inspect endpoint needs flags.read. Unlike the console box it also accepts attributes. At least one of identifier, account or device is required.
curl -s -X POST "https://flags.example.com/api/flags/$FLAG_ID/environments/staging/inspect" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{"identifier":"user-9","attributes":{"plan":"pro","country":"NG"}}'{
"status": "success",
"message": "OK",
"data": {
"enabled": true,
"reason": "RULE_MATCH",
"bucketBy": "user",
"matchedSegment": null,
"bucket": 4127,
"cutoff": 0,
"rolloutPercentage": 0,
"inRollout": false,
"targeted": false,
"ruleMatched": true,
"variantBucket": null
}
}To evaluate from your app instead, send the identifiers and attributes to the Evaluation API as shown under Describe the person, which authenticates with an API key. See Update an environment's configuration and Check what someone would see.
What to check#
- Use Check who gets this flag with a listed person and confirm the reason is
TARGETED_USER. - Call the inspect endpoint with attributes and confirm
RULE_MATCHfor a person who should match and not for one who should not. - Remember the order: targeting lists, then segments, then rules, then prerequisites and the rollout.
- Open History & rollback and confirm a new version recorded the change.
If something goes wrong#
A listed person does not get the flag
Why: The flag is off or the kill switch is on (check the badge), the toggle Always on for these people is off, or the identifier differs in case or spacing from what the app sends. The reasons DISABLED and KILL_SWITCH point to the first two.
Fix: Check the person with Check who gets this flag, then copy the identifier from your app instead of retyping it.
A rule never matches
Why: The attribute name must equal the key your app sends. Matching is case-sensitive and a missing attribute never matches.
Fix: Try the sample person in Test these rules, then log what the SDK sends.
Save changes is greyed out
Why: A rule has an empty attribute or value, a rule has no condition, or an attribute name uses characters other than letters, numbers and . _ : -.
Fix: Read the message under the Rules step: it names the problem. Complete or delete the rule.
Add rule is greyed out, or a condition cannot be added
Why: A flag environment holds at most 20 rules and each rule at most 10 conditions. The button's tooltip says At most 20 rules or At most 10 conditions in a rule.
Fix: Merge rules with an is one of condition, or move the audience into a segment.
Refused with APPROVAL_REQUIRED
Why: The environment requires approval, and targeting changes cannot be carried by a release, which changes only on/off and the percentage.
Fix: Make the targeting change where approval is not required, or ask an Admin to switch Require approval off for the moment. See Put production behind review.
Forbidden in production
Why: Developers and Product managers cannot change targeting in a production environment.
Fix: Ask a Release manager or an Admin.
NO_IDENTIFIER or INVALID_ATTRIBUTES from the Evaluation API
Why: The flag rolls out by an identifier the request lacks, or the attributes were not a JSON object, were malformed or were over 8 KB.
Fix: Send the identifier of the kind in Roll out by, or fix the attributes.
Good habits#
- Use the same identifier strings everywhere: copy them from your app instead of retyping.
- Send the attributes your rules use on every evaluation, not only some of them.
- Prefer a segment over a long list you would paste into several flags.
- Test rules with a person who should match and one who should not before you save.
- Keep lists to the people you really mean to name. Long-lived audiences belong in rules or segments.
Good to know#
Lists and rules ignore the rollout percentage
Does targeting work when the flag is off?
DISABLED. The kill switch is checked even earlier.Can I match on more than one attribute?
Are identifiers case-sensitive?
equals compare exactly, so User-123 and user-123 are different people.