No results for ""
EXPAND ALL
  • Home
  • API docs

Targeting rules

Read time: 6 minutes
Last edited: Nov 05, 2024

Overview

This topic explains how to use flag targeting rules to serve flag variations to different contexts based on their attributes.

About targeting rules

Targeting rules, including the default rule, are all listed on a feature flag's targeting page.

Each targeting rule includes a description, one or more conditions, and a rollout.

Each condition has three parts:

  • Context kind and attribute information, which defines the scope of the condition's impact.
    • For segment rules, this is always "context," because segment rules check whether a context is part of a segment.
    • For mobile rules, this is always the application or device context kind, and then an attribute that you select.
    • For custom rules, this is the context kind and attribute that you select, such as "user" and "email address." To learn more, read Attributes.
  • An operator, which sets differentiating characteristics of the attribute, such as limiting the condition to emails that end with certain extensions. If a condition specifies multiple values for the operator to track, the operator iterates over the array. To learn more, read Operators.
  • A value, which identifies the attribute by a value you specify. such as .edu or v1. For segment rules, this is the segments that you select.

The rollout describes what variation of the flag to serve when the end user matches the targeting rule. You can set this to any of the variations of the flag, or to a percentage rollout. If you want to roll out the selected variation gradually, you can add a progressive rollout or guarded rollout to the targeting rule. To learn more, read Releasing features with LaunchDarkly.

Here is an image of a targeting rule:

A targeting rule that serves "Available" to all user contexts that contain an "email" attribute with a value that ends in ".edu".
A targeting rule that serves "Available" to all user contexts that contain an "email" attribute with a value that ends in ".edu".

By default, all the targeting rules on the flag targeting page are expanded, so that you can view their names and a summary of their conditions. To view only the names of the targeting rules, click the collapse icon from the top of the page.

Targeting rules limitations

There is not a specific limit on the number of targeting rules you can have on a flag. As a general rule, the SDK initialization time scales with the combination of the total number of flags in the project, the size of the flag variations, and the number and complexity of targeting rules across all flags in the environment. To discuss specifics for your account, start a Support ticket.

Attributes

LaunchDarkly allows you to create your own attributes. For instance, you might want to target contexts based on plan, group, role, or location.

Here is an example of a context with custom attribute values:

"context": {
"kind": "user",
"name": "Sandy",
"email": "sandy@example.com",
"gymMember": "true"
}

Using attributes, you could show some features to customers on your regular plan, and additional features to customers on your premium plan. Or you could roll out a new feature to 30% of end users at a particular location, rather than 30% of all end users. To learn more, read Context attributes.

In each targeting rule, you can choose an attribute specific to your chosen context kind using the "Attribute" menu.

The "Attribute" menu, showing attributes for a user context.
The "Attribute" menu, showing attributes for a user context.

If an attribute is an object, then in your targeting you can use / as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes "city," "state," and several other fields, then you can use /address/city in your targeting.

From here, you can also select whether to include or exclude all contexts of a particular context kind based on whether they are part of a segment. To learn more, read Segments.

Operators

LaunchDarkly supports the following operators:

OperatorAttribute typeMeaning
is one of (=), is not one of (!=)string, number, boolean, dateExact match
ends with, does not end withstringString suffix match
starts with, does not start withstringString prefix match
matches regex, does not match regexstringRegular expression match
contains, does not containstringSubstring match
greater than (>), less than (<), greater than or equal to (>=), less than or equal to (<=)numberNumeric comparisons
before, afterdateDate comparisons. Dates must be formatted in UNIX milliseconds or a string in RFC-3339 format. To learn more, read Representations of data/time values.
semantic version is one of (=), is not one of (!=), greater than (>), less than (<), greater than or equal to (>=), less than or equal to (<=)string

Semantic version comparison. Valid string attributes must follow the semantic versioning specification, although LaunchDarkly allows you to omit the PATCH version. For example, 2.0 is a valid semantic version. To learn more, read Semantic versioning.

For semantic versions, "greater than or equal" (>=) is persisted as "not less than." Similarly, "less than or equal" (<=) is persisted as "not greater than." To learn more, read Operators.

Types of targeting

LaunchDarkly supports the following targeting types:

  • Bulk targeting
  • Converting rules into segments
  • Custom rules
  • Individual targeting
  • Mobile targeting
  • Segment targeting
  • Testing flag targeting

You can also set flag prerequisites to make flags depend on other flags being enabled to take effect. To learn more, read Flag prerequisites.

Evaluation order

Flags evaluate flag prerequisites and rules from top to bottom.

This diagram represents rule matching behavior:

A tree diagram showing rule matching behavior.
A tree diagram showing rule matching behavior.

At each step in the process, if the context instance matches the rule, it receives the appropriate variation. If it does not match the rule, it moves on to the next rule.

Configure your SDK: Evaluating flags

Here is how a context instance moves through a flag evaluation:

  1. If your app can't connect to LaunchDarkly, the context receives the fallback value. Otherwise, it moves to the next step.
  2. If targeting is off, the context receives the default off variation. Otherwise, it moves to the next step. To learn more, read Set default values.
  3. If the flag has prerequisites, and the context doesn't meet the prerequisites, it receives the default off variation. Otherwise, it moves to the next step. To learn more, read Flag prerequisites.
  4. If the context is individually targeted, it receives the chosen variation in the individual targeting rule. Otherwise, it moves to the next step. To learn more, read Individual targeting.
  5. If the context meets a flag rule, it receives the chosen variation. Otherwise, it moves to the next step. If there are multiple flag rules, the context moves through the rules from top to bottom.
  6. If the context doesn't meet any of the previous criteria, it receives the default on variation. To learn more, read Set default values.

Here is an image of two targeting rules:

Two rules, targeting a segment and an organization context.
Two rules, targeting a segment and an organization context.

In this example, the first rule (if the segment is not in Beta users) is evaluated before the second rule (if the organization key is Beta).

You can re-order rules by clicking and dragging them into different positions. Alternatively, you can click the overflow menu of the flag targeting rule you want to move. Then, select Move rule up or Move rule down.

Rule duplication

You can create new targeting rules by duplicating a flag's existing targeting rule and modifying the new rule.

To duplicate an existing targeting rule:

  1. Click on the flag rule's three-dot overflow menu and choose "Duplicate rule." A new rule appears.
  2. Make at least one change to the existing rule or the new rule.
  3. Click Review and save.

Here is an image of the "Duplicate rule" option in the rule menu:

A feature flag's "Duplicate rule" option called out.
A feature flag's "Duplicate rule" option called out.

The new rule appears below the original rule. You must make at least one change to either the existing rule or the new rule before saving your changes, to prevent two exact duplicate rules on the same flag.