• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Targeting rules

Read time: 14 minutes
Last edited: Nov 21, 2023

Overview

This topic explains how to use targeting rules to target segments or contexts based on their attributes.

Each feature flag can include a combination of individual targets and targeting rules. To learn more about individual targets, read Individual targeting.

Each feature flag must include a default rule. To learn more, read Setting the default rule, below.

Migration flags are different

Migration flags require different configuration than other types of flags. You can only configure a migration flag's rollout options by percentages alloted to different flag variations. To learn more, read Targeting with migration flags.

Understanding targeting rules

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

Each targeting rule includes an 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. To learn more, read Percentage rollouts.

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 Targeting tab are expanded, so that you can view their names and a summary of their conditions. To view only the names of the targeting rules, select Collapse all from the top of the Targeting tab.

Targeting segments

Segments are lists of contexts that you can use to manage flag targeting behavior in bulk. You can target segments to release features to groups of contexts or end users at once.

We recommend using a segments when you want to target the same group of contexts using multiple flags. You can target the segment in each flag, rather than recreating a targeting rule or set of rules for many flags.

To target segments:

  1. If this is your first targeting rule, find the "Target segments" card and click Get started:
The Target segments card on the flag's "Targeting" tab.
The Target segments card on the flag's "Targeting" tab.

If you already have targeting rules for your flag, click + Add rule and select "Segment":

The "+ Add rule" menu, with Segment called out.
The "+ Add rule" menu, with Segment called out.
  1. (Optional) Enter a name for the rule.
  2. In the Operator menu, select whether you want contexts in these segments or not in these segments to match the targeting rule.
  3. In the Segments menu, enter or select the segments you want to target.
  4. (Optional) Click the + to add additional clauses to your targeting rule.
  5. In the Rollout field, select the variation to serve, or set a percentage rollout.

Here is an example of a targeting rule for segments:

A targeting rule for segments.
A targeting rule for segments.

To learn more, read Segments.

Targeting individuals

You can target specific contexts using individual targeting. To learn how, read Individual targeting.

Targeting mobile apps and devices

If you are using a mobile SDK that supports environment attributes, you can target your mobile applications based on automatically collected details about your application, application version, and device. To learn more about configuring your mobile SDKs to support this targeting, read Automatic environment attributes.

Mobile environment attributes must be collected first

You can only create a "Mobile" targeting rule, and target mobile apps and devices based on automatically collected mobile environment attributes, if you have completed the following:

  • your feature flag has its Client-side SDK availability set to include "SDKs using Mobile key." To learn more, read Creating flags.
  • you have already started to collect mobile environment attributes. LaunchDarkly must receive an evaluation context with this information before it enables the option to create a mobile targeting rule.

If you are using other mobile SDKs, you can target your mobile applications using custom targeting rules. With custom targeting rules, you can target your mobile applications based on any attributes that you have manually added to your contexts.

To target mobile apps and devices:

  1. If this is your first targeting rule, find the "Target mobile apps and devices" card and click Get started:
The Target mobile apps and devices card on the flag's "Targeting" tab.
The Target mobile apps and devices card on the flag's "Targeting" tab.


If you already have targeting rules for your flag, click + Add rule and select "Mobile":

The "+ Add rule" menu, with Mobile called out.
The "+ Add rule" menu, with Mobile called out.
  1. (Optional) Enter a name for the rule.
  2. In the Attribute menu, select the application or device attribute that you want to target on. By default, mobile targeting rules include clauses for the application ID, application version, and device OS.
  3. (Optional) Click + to add additional clauses to your targeting rule, or click - to remove existing clauses from your targeting rule.
  4. In the Operator menu, select the operator for your clause.
  5. In the Values menu, enter the values to check against.
  6. In the Rollout field, select the variation to serve, or set a percentage rollout.

Here is an example of a targeting rule for mobile apps:

A targeting rule for mobile apps.
A targeting rule for mobile apps.

Custom targeting rules

You can create custom targeting rules using any context kinds and any context attributes.

To create a custom targeting rule:

  1. If this is your first targeting rule, click Create custom rule. If you already have targeting rules for your flag, click + Add rule and select "Custom":
The "+ Add rule" menu, with Custom called out.
The "+ Add rule" menu, with Custom called out.
  1. (Optional) Enter a name for the rule.
  2. Select an option from the Context kind menu:
  • Choosing a specific context kind lets you target on attributes for contexts of that kind.
  • "Context kind" lets you choose one or more context kinds to target. If you choose "Context kind," skip to step 5.
  1. In the Attribute menu, select one of this context's attributes.
  2. In the Operator menu, select the operator for your clause.
  3. In the Values menu, enter one or more values to check against.
  4. In the Rollout field, select the variation serve, or set a percentage rollout.
  5. Click Review and save.
Custom targeting rules can include mobile application data

If you are using a mobile SDK that supports environment attributes, you can target your mobile applications based on details about your application, application version, and device using a mobile targeting rule. To create custom targeting rules using this same context information, use the ld_application and ld_device context kinds.

If you are using other mobile SDKs, you can target your mobile applications using any context attributes that you have created.

If a targeting rule references any context kinds or attributes with null values, or that do not exist for a given context, then the flag skips that rule. For example, in a rule that checks "region is one of Canada," any context whose region attribute is not set or is set to null does not match the rule. Similarly, in a rule that checks "region is not one of Canada," any context whose region attribute is not set or is set to null does not match the rule. This behavior ensures that your rules only target contexts for which you explicitly have attribute information.

You can add multiple conditions to a rule. Here is how rules handle multiple conditions and values:

  • Contexts must meet all the conditions in a rule to match the rule. If any of the conditions are not met, the context will not match the rule.
  • If a condition has multiple values, LaunchDarkly considers the condition met if there is a match on any of the values.
  • If an attribute has an array value, LaunchDarkly treats it as multiple values and allows any of the values within the array to match a rule.

You can also use the REST API: Update feature flag

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 the "country" attribute for a user context.
The "Attribute" menu, showing the "country" attribute 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 Representing 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 Using 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.

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.

Experimentation

Experimentation is available for Pro and Enterprise plans

Experimentation is available to customers on a Pro or Enterprise plan. To learn more, read about our pricing. To add Experimentation to your plan, contact Sales.

After you save a targeting rule, here's how to start an experiment:

  1. Click the pencil edit icon to edit the rule.
  2. Click the graph icon and select "Run an experiment on this rule" to create an experiment.

To learn more, read Creating experiments.

Here is an image of the graph icon on a flag's targeting rule:

A targeting rule with the "graph" icon called out.
A targeting rule with the "graph" icon called out.

Setting the default rule

LaunchDarkly defines a final default rule, sometimes called the "fallthrough" rule, for any contexts that don't match any of the previous targeting rules on the page. As with other rules, you can choose to serve a specific variation, or apply a percentage rollout to any remaining contexts.

Here is an image of a default rule:

A flag's default rule.
A flag's default rule.

Now, all contexts that have not been targeted by any other rules will receive false.

Setting the default off variation

When the toggle is turned off, LaunchDarkly will serve the default off variation for your feature flag. For boolean flags, the default off variation is set to false. For multivariate flags, you select one of your custom variations. You can customize the default off variation for both boolean and multivariate flags in the Targeting tab.

If you do not specify a default off variation, then the SDK will return the fallback value defined in your code.

Setting a fallback value in your SDK call

Regardless of how you set up targeting for your feature flag, each time you evaluate a flag from the SDK, you must include a fallback value as one of the parameters. This fallback value is the value served to the context if the SDK cannot connect to LaunchDarkly. To learn more, read Evaluating flags.

Evaluation order

The Targeting tab evaluates 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: Configuring variations

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 Setting 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 Setting 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.

Converting rules into segments

You may require complex targeting rules to successfully perform feature launches. You can convert a targeting rule into a reusable standard segment from the flag's Targeting page.

To convert a rule into a segment:

  1. Navigate to the flag's Targeting tab.
  2. In the targeting section or the rule matching section, click the overflow menu of the rule you wish to convert. The overflow menu appears.
  3. Click "Convert to segment." The "Convert to segment" dialog appears.
  4. Give your segment a human-readable Name and a Key.
  5. (Optional) Add a Description.
  6. (Optional) Select a tag or create a new tag from the Tags menu.
  7. Click Save segment. A confirmation appears indicating that you've created a new segment.

A new rule targeting the newly created segment appears in the list of targeting rules.