Targeting, Segments,

Targeting, Segments, and Rollouts

Targeting lets a feature flag serve different variations to different evaluation contexts. Configure it independently for each environment, combine conditions into ordered targeting rules, reuse audiences with segments, and distribute matched contexts with deterministic percentage rollouts.

The API stores this configuration, while @flagforge/core applies the same evaluation semantics in the REST API and the TypeScript SDK. A context with the same stable key receives the same rollout result for a given flag.

Configure targeting for an environment

Targeting is part of a flag's environment configuration. Replace the configuration for one environment with:

curl -X PUT "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/flags/new-checkout/targeting" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "enabled": true,
    "defaultVariationKey": "off",
    "offVariationKey": "off",
    "rules": [
      {
        "id": "pro-users",
        "conditions": [
          { "attribute": "plan", "operator": "equals", "values": ["pro"] }
        ],
        "variationKey": "on"
      }
    ]
  }'

The PUT operation replaces the targeting configuration for the specified environment. Keep defaultVariationKey and offVariationKey pointed at variation keys defined on the flag. Targeting rules and rollout branches also refer to variations by key, not by numeric position.

Each rule has an identifier, a list of conditions, and either a fixed variationKey or a rollout. Rules are evaluated in array order. The first rule whose conditions all match determines the result.

Conditions and operators

A condition reads key from the evaluation context or another named attribute. The condition matches when its operator succeeds for any value in values. Multiple conditions in one rule are combined with logical AND.

Set negate to true to invert a condition. If an attribute is absent, a normal condition does not match; a negated condition therefore matches the absent-attribute case.

For example, this rule requires both a production plan and a supported country:

{
  "id": "pro-launch-countries",
  "conditions": [
    { "attribute": "plan", "operator": "equals", "values": ["pro"] },
    { "attribute": "country", "operator": "in", "values": ["US", "CA"] }
  ],
  "variationKey": "on"
}

An application supplies these values in its evaluation context:

const context = {
  key: "user-123",
  attributes: { plan: "pro", country: "US" },
};

Create and reuse segments

A segment is a named set of conditions that can be referenced by multiple targeting rules. Create one through the project-scoped segments endpoint:

curl -X POST "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/segments" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta-users",
    "name": "Beta users",
    "description": "Users enrolled in the beta program",
    "conditions": [
      { "attribute": "beta", "operator": "equals", "values": [true] }
    ]
  }'

Reference the segment from a flag rule with inSegment:

{
  "id": "beta-rollout",
  "conditions": [
    { "attribute": "segment", "operator": "inSegment", "values": ["beta-users"] }
  ],
  "variationKey": "on"
}

All conditions in a segment must match. Segment conditions can themselves reference segments with inSegment; unresolved segment keys do not match, and cyclic references are treated as non-matches.

Add a deterministic percentage rollout

A rollout is a list of weighted branches. Weights use a resolution of 100000, so 25000 represents 25% and 75000 represents 75%:

{
  "id": "pro-rollout",
  "conditions": [
    { "attribute": "plan", "operator": "equals", "values": ["pro"] }
  ],
  "rollout": {
    "branches": [
      { "variationKey": "on", "weight": 25000 },
      { "variationKey": "off", "weight": 75000 }
    ]
  }
}

By default, FlagForge buckets on the context key. You can set bucketBy to an attribute when the rollout should follow another stable dimension, such as an account:

"rollout": {
  "bucketBy": "accountId",
  "branches": [
    { "variationKey": "on", "weight": 10000 },
    { "variationKey": "off", "weight": 90000 }
  ]
}

The bucket is derived from the flag key and bucket value, so different flags distribute the same subject independently. Use stable identifiers for key and bucketBy; changing them can move a context to another branch. If a configured bucket attribute is missing, evaluation falls back to the context key.

Understand the resulting evaluation

FlagForge evaluates a flag in this order:

1. If the environment configuration is disabled, it serves offVariationKey.

2. It checks targeting rules in order. The first matching rule serves its fixed variation or rollout branch.

3. If no rule matches, it serves defaultVariationKey.

The result includes the selected variationKey, its value, and a reason. Reasons identify an off flag (OFF), a matching rule (RULE_MATCH, including its rule ID and index), a fallthrough (FALLTHROUGH), or an evaluation error (ERROR). The SDK and API use these same semantics because both use the shared evaluation engine.

For the complete evaluation order and result model, see How Evaluation Works. For the exact targeting request contract, see Replace flag targeting.