Targeting rules

Targeting rules decide which variant a user receives when a flag is on. Each environment has its own rules, so a rule in Development does not affect Production.

How rules workCopy Anchor Link

A flag's rules form an ordered list. When a flag is on, Toggld checks each rule from top to bottom:

1. A rule matches when all of its conditions match and all of its segment references match.
2. The first matching rule wins. Toggld ignores the rules below it.
3. If no rule matches, Toggld serves the default variant with the reason STATIC.

When the flag is off, Toggld skips the rules and serves the off variant with the reason DISABLED.

Each rule serves one of these:

A rule with no conditions and no segments matches everyone. Use it as a catch-all at the end of the list.

Add a rule in the dashboardCopy Anchor Link

1. Open the flag and select the environment tab.
2. In Who gets what, select Add rule. The new rule matches anyone and serves the default variant.
3. Optionally, give the rule a name. The name is the rule's description.
4. Select Condition. Enter the attribute, choose an operator, enter the value, and choose the value type.
5. Optionally, select Segment to reference a segment. The button appears when the workspace has segments.
6. Under Gets, choose a variant, or choose Split by percentage for a rollout.
7. Drag the rule by its handle to the right position, or use Move up and Move down in the rule's ⋯ menu. The menu also has Duplicate and Delete rule.
8. Select Save environment.

The path in Who gets what reads from top to bottom: the environment switch, then each rule in order, then Everyone else. When the switch is off, everyone gets the variant in If off.

After you save, select Test a user to see which variant a context gets, and why. The dialog uses the saved rules, not your draft.

ConditionsCopy Anchor Link

A condition compares one attribute of the evaluation context with a value.

{ "attribute": "plan", "operator": "eq", "value": "pro" }

• attribute is the name of a top-level context attribute, such as plan or targetingKey. Toggld does not read nested paths. The attribute user.plan matches a context key that is literally named user.plan, not a plan field inside a user object.
• operator is one of the operators below.
• value is the operand. The exists and notExists operators do not use it.

OperatorsCopy Anchor Link

Notes:

• Missing attributes. If the context does not have the attribute, or its value is null, every operator except exists and notExists returns no match. This includes ne and notIn. To match "not pro, or no plan at all", add a separate rule that uses notExists.
• Equality compares the JSON type and the value. Objects and arrays match when their contents are equal.
• Text operators are case-sensitive and work only on strings. contains checks for a substring. It does not check whether an array contains an item. Use in for that.
• Number operators work only when both the attribute and the value are numbers.

Match the value typeCopy Anchor Link

Toggld never converts types. A condition matches only when the context sends the same JSON type as the rule.

Follow these rules to avoid surprises:

• Keep identifiers, such as account numbers and ZIP codes, as strings. A number loses leading zeros: 00123 becomes 123.
• Send numbers as numbers when you compare them with lt, lte, gt, or gte.
• Send each attribute with the same type every time, in every service.
• In the dashboard, set the value type (Text, Number, Boolean, or JSON) to match what your code sends. Number and text operators always use their own type. For is one of and is not one of, type each value and press Enter or a comma. With the JSON value type, enter a JSON array instead, such as ["001", "002"] or [18, 25].

The API validates operands when you save. Number operators require a finite number, text operators require a string, and in and notIn require an array. Other operators require a value. Invalid rules return HTTP 422 with the error FlagValidationError.

Use segments in rulesCopy Anchor Link

A rule can reference segments. In the dashboard, select Segment in the rule and choose a segment. Choose in segment or not in segment.

{
  "id": "beta-testers",
  "conditions": [],
  "segments": [{ "segment": "beta-testers" }],
  "serve": { "type": "variant", "variant": "on" }
}

• Segment references are combined with AND, both with each other and with the conditions.
• "negate": true means "not in the segment".
• Toggld rejects a rule that references a segment that does not exist.
• To target different audiences per environment, reference different segments in each environment's rules.

Rule formatCopy Anchor Link

In the API, targeting is an array of rules. This example serves on to beta users, then rolls out to 20% of everyone else:

{
  "targeting": [
    {
      "id": "beta",
      "description": "Beta plan",
      "conditions": [{ "attribute": "plan", "operator": "eq", "value": "beta" }],
      "serve": { "type": "variant", "variant": "on" }
    },
    {
      "id": "rollout",
      "conditions": [],
      "serve": {
        "type": "rollout",
        "bucketBy": "targetingKey",
        "splits": [
          { "variant": "on", "weight": 20 },
          { "variant": "off", "weight": 80 }
        ]
      }
    }
  ]
}

Every variant that a rule serves must exist in the same environment. Send the rules in a PATCH request to /api/v1/flags/{key} with a management key for the target environment. See Create and edit flags.