Read time: 5 minutes
Last edited: Feb 01, 2023
This topic explains how to use targeting rules to target segments of users based on their built-in and custom user attributes.
Targeting rules can have one or more conditions.
Each condition has three parts:
- A built-in or custom user attribute, which defines the scope of the condition's impact, such as only targeting an email address. To learn more, read User 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
Here is an image of a user targeting rule:
To create a rule that serves
true to all users whose email address ends with
- Click Add rules.
- Enter a name for the rule.
ends withfrom the Select an operator menu.
gmail.comin the Enter some values field.
truefrom the serve menu.
- (Optional) If you need to undo the changes you just made, click the undo arrow icon to discard all changes.
- Click Review and save.
If a targeting rule references any custom attributes with
null values, or that do not exist for a given user, then the flag skips that rule. For example, in a rule that checks "region is one of Canada," any user 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 user whose region attribute is not set or is set to null does not match the rule. This behavior ensures that your rules only target users for whom you explicitly have attribute information.
You can add multiple conditions to a rule. Here is how rules handle multiple conditions and values:
- Users must meet all the conditions in a rule to match the rule. If any of the conditions are not met, the user 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 a custom attribute has an array value, LaunchDarkly treats it as multiple values and allows any of the values within the array to match a rule.
If you want only a portion of users 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, 25% of users will receive the
To learn more, read Percentage rollouts.
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:
LaunchDarkly includes built-in attributes for users. Here are some examples of common user attributes:
For a full list of built-in user attributes, read Built-in user attributes.
LaunchDarkly also allows you to create your own custom user attributes. For instance, you might want to target users based on plan, group, role, location, or organization. Using custom user attributes, you could show some features to users on your regular plan, and additional features to users on your premium plan. Or you could roll out a new feature to 30% of organizations, rather than 30% of users.
To learn more, read Custom user attributes.
LaunchDarkly supports the following operators:
|is one of (=), is not one of (!=)||string, number, boolean, date||Exact match|
|ends with, does not end with||string||String suffix match|
|starts with, does not start with||string||String prefix match|
|matches, does not match||string||Regular expression match|
|contains, does not contain||string||Substring match|
|greater than (>), less than (<), greater than or equal to (>=), less than or equal to (<=)||number||Numeric comparisons|
|before, after||date||Date comparisons. Dates must be formatted in UNIX milliseconds or a string in RFC-3339 format. To learn more, read Representing data/time values.|
|user is in segment, user is not in segment||segment names||User is included or excluded by the targeting rules for the named segments. To learn more, read Building user segments.|
|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.
To associate pre-login (anonymous user) behaviors with post-login (known user) behaviors to get a singular view of a user flow, you should use a custom attribute and the advanced option for percentage rollouts that allows you to rollout based on a different attribute.
Here's how to do this:
- Store a unique identifier for the anonymous user into a cookie. A session ID or UUID works well.
- Use this unique identifier as both the user's key and a custom attribute until the user logs in. The custom attribute can be named anything, but for this example it is named
- While the user is logged in, set the user's key to their real (primary) user key, but continue to use the unique identifier stored in the cookie as the user's
- For all flags, or for those that may affect logged out users, use the advanced option for all percentage rollouts to do rollouts based on the
To learn more about anonymous users, read Anonymous users.
secondary attribute is a special attribute. The SDKs incorporate this attribute into the variation bucket assignment hash automatically when it is included in your user object. Unlike other attributes, you cannot use the
secondary attribute in targeting rules.
LaunchDarkly defines a final default rule, sometimes called the "fallthrough" rule, for any users 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 users.
Here is an image of the percentage rollout section:
Now, 50% of all users who have not been targeted by any other rules will receive
If you do not want to target users based on user key or any custom attributes, you can use the default rule to control the flag's rollout for all users.
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.
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 user if the SDK cannot connect to LaunchDarkly. To learn more, read Evaluating flags.
The Targeting tab evaluates rules top-down. Imagine a highway with exits along the way. All of your users will start at the top and then gradually exit the highway when they match a rule.
If a user matches multiple rules, the first matching rule applies.
Here is a diagram representing rule matching behavior:
Here, we have two custom rules. Rules are evaluated top down, so in this example, the first rule (
country is one of
Canada) is evaluated before the second rule (
groups is one of
beta_testers). If a user matched both rules, the first rule would take priority.
Here is an image of two targeting rules:
Rules can be re-ordered by clicking on the left edge of a rule and dragging it up or down.
You may require complex targeting rules to successfully perform feature launches. You can convert a targeting rule into a reusable segment from the flag's Targeting page.
Here is an image of the "Convert individual user targets to segment" dialog:
To convert a rule to a segment:
- Navigate to the flag's Targeting page.
- In the user targeting section or the rule matching section, click the overflow menu of the rule you wish to convert. The overflow menu appears.
- Click "Convert to segment". The "Convert to segment" window appears:
- Give your segment a human-readable Name.
- (Optional) Add a Description.
- (Optional) Choose any Tags from the menu menu.
- Click Save segment. A confirmation appears indicating that you've created a new segment.
After you click "Convert to segment", targeted users are cleared. A new segment rule targeting the newly created segment
test-12345 appears at the top of the list of targeting rules.
Here is an image of the targeting section: