Targeting rules

Overview

This topic explains how to use targeting rules to target sets of contexts based on their attributes.

Creating targeting rules

Targeting rules can have one or more conditions.

Each condition has three parts:

• A context kind and attribute, which defines the scope of the condition's impact, such as only targeting an email address for the selected context kind. 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.

Here is an image of a targeting rule:

To create a targeting rule:

1. Click Add rules.

2. Enter a name for the rule.

3. Choose a context kind from the "context kind" menu.

   a. Alternatively, if you choose "context kind" from the menu, you can select multiple context kinds to target simultaneously. If you do this, skip to step 7.

4. Choose an attribute from the "Select an attribute" menu.

5. Choose an operator from the "Select an operator" menu.

6. Enter a value in the "Enter some values" field.

7. Choose a variation from the "serve" menu.

8. (Optional) If you need to undo the changes you just made, click the undo arrow icon to discard all changes:

   

9. Click Review and save.

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.

Percentage rollouts

If you want only a portion of contexts matching a rule to receive a particular variation, you can serve a percentage rollout.

Here is an image of the percentage rollout section:

In this example, 50% of contexts will receive each variation.

To learn more, read Percentage rollouts.

Experimentation

After you save a targeting rule, you can click the graph icon to run an experiment on the rule. To learn more, read Creating experiments.

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

Attributes

LaunchDarkly allows you to create your own attributes. For instance, you might want to target contexts based on plan, group, role, or location. 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 "Select an attribute" menu.

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:

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:

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.

Evaluation order

The Targeting tab evaluates rules top-down. Imagine a highway with exits along the way. All of your contexts will start at the top and then gradually exit the highway when they match a rule.

First, the individual targeting rules are evaluated, top-down. To learn more, read Individual targeting. Next, the custom rules are evaluated, top-down. Finally, if a context does not match any of the individual or custom rules, it falls through and is served the default rule.

Here is a diagram representing rule matching behavior:

Rules are evaluated from top to bottom. If a context instance matches both rules, the first rule takes priority.

Here is an image of the two targeting rules:

In this example, the first rule (if the user context is not in Beta users) is evaluated before the second rule (if the account context plan type is Beta).

Rules can be re-ordered by clicking on the left edge of a rule and dragging it up or down.

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 learn how, read Converting a rule into a standard segment.