Targeting Rules

Targeting rules determine which variant a user receives based on their context.

Evaluation Context

Context is data you pass when evaluating a flag:

const context = {
  targetingKey: 'user-123',      // Required: unique user identifier
  email: 'user@example.com',
  plan: 'premium',
  country: 'SE',
  version: '2.1.0'
};
 
const value = await client.getBooleanValue('feature', false, context);

The targetingKey is required - it identifies the user for consistent rollouts.

Rule Structure

Each rule has:

Conditions - Criteria that must match
Variant - The value to return if conditions match
Priority - Order of evaluation (first match wins)

Rule 1 (priority 1): IF email ends with "@company.com" THEN return "enabled"
Rule 2 (priority 2): IF plan equals "enterprise" THEN return "enabled"
Default: return "disabled"

Rules are evaluated in priority order. First match wins.

Operators

String Operators

Operator	Description	Example
equals	Exact match (case-sensitive)	`email` equals `"admin@company.com"`
equals (ignore case)	Exact match (case-insensitive)	`country` equals (ignore case) `"se"`
contains	Substring match	`email` contains `"test"`
starts with	Prefix match	`email` starts with `"admin"`
ends with	Suffix match	`email` ends with `"@company.com"`
matches regex	Regular expression	`email` matches regex `".*@(alpha\|beta)\\.com"`

Numeric Operators

Operator	Description	Example
`=` (equals)	Equal to	`age = 25`
`>` (greater than)	Greater than	`age > 18`
`>=` (greater or equal)	Greater than or equal	`version >= 2.0`
`<` (less than)	Less than	`version < 3.0`
`<=` (less or equal)	Less than or equal	`seats <= 10`

Combining Conditions

Rules can have multiple conditions combined with AND:

IF email ends with "@company.com"
   AND plan equals "enterprise"
   AND seats >= 10
THEN return "enabled"

All conditions must match for the rule to apply.

Gradual Rollouts

Rollouts release a feature to a percentage of users:

10% -> variant-a
20% -> variant-b
70% -> control

How it works:

User's targetingKey is hashed
Hash maps to a bucket (0-99)
Bucket determines which variant they receive

Properties:

Deterministic - Same user always gets the same variant
Consistent - Increasing percentage doesn't reassign existing users
Statistically valid - Even distribution for A/B tests

Percentages must sum to 100%. If they don't, the last variant receives the remainder.

Combining Rules and Rollouts

Targeting rules and gradual rollouts work together with a clear priority:

Targeting rules are evaluated first - if any rule matches, its value is returned immediately
Rollout applies when no rules match - only users who don't match any targeting rule enter the gradual rollout

Example setup:

Targeting Rules:
  Rule 1: IF user in segment "internal" THEN return "enabled"
  Rule 2: IF user in segment "beta-testers" THEN return "enabled"

Gradual Rollout (for everyone else):
  10% -> "enabled"
  90% -> "disabled"

This pattern lets you:

Give 100% access to internal users and beta testers (via rules)
Gradually roll out to remaining users (via gradual rollout)

On this page