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

    EDIT ON GITHUB

    Targeting rules

    Read time: 5 minutes
    Last edited: Feb 01, 2023

    Overview

    This topic explains how to use targeting rules to target segments of users based on their built-in and custom user attributes.

    Creating targeting rules

    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 gmail.com.

    Here is an image of a user targeting rule:

    A user targeting rule.
    A user targeting rule.

    To create a rule that serves true to all users whose email address ends with gmail.com:

    1. Click Add rules.
    2. Enter a name for the rule.
    3. Choose email from the Select an attribute menu.
    4. Choose ends with from the Select an operator menu.
    5. Enter gmail.com in the Enter some values field.
    6. Choose true from the serve menu.
    7. (Optional) If you need to undo the changes you just made, click the undo arrow icon to discard all changes.
    8. 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.

    Percentage rollouts

    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:

    The percentage rollout section.
    The percentage rollout section.

    In this example, 25% of users will receive the true variation.

    To learn more, read Percentage rollouts.

    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, 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:

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

    User attributes

    LaunchDarkly includes built-in attributes for users. Here are some examples of common user attributes:

    • key
    • firstName
    • lastName
    • email
    • avatar

    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.

    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, does not matchstringRegular 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.
    user is in segment, user is not in segmentsegment namesUser 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 (<=)stringSemantic 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.

    Maintaining user experience across anonymous and logged-in states

    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:

    1. Store a unique identifier for the anonymous user into a cookie. A session ID or UUID works well.
    2. 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 uniqueId.
    3. 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 uniqueId custom attribute.
    4. 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 uniqueId custom attribute.

    To learn more about anonymous users, read Anonymous users.

    secondary attribute

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

    Setting the default rule

    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:

    A percentage rollout, set to 50%.
    A percentage rollout, set to 50%.

    Now, 50% of all users who have not been targeted by any other rules will receive true.

    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.

    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 user if the SDK cannot connect to LaunchDarkly. To learn more, read Evaluating flags.

    Evaluation order

    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:

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

    Here, we have two custom rules. Rules are evaluated top down, so in this example, the first rule (email ends with gmail.com and country is one of USA or 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:

    Two custom rules targeted at user groups.
    Two custom rules targeted at user groups.

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

    Converting a rule into a segment

    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:

    The "Convert to segment" dialog.
    The "Convert to segment" dialog.

    To convert a rule to a segment:

    1. Navigate to the flag's Targeting page.
    2. 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.
    3. Click "Convert to segment". The "Convert to segment" window appears:
    A flag rule, with the "Convert to segment" option called out.
    A flag rule, with the "Convert to segment" option called out.
    1. Give your segment a human-readable Name.
    2. (Optional) Add a Description.
    3. (Optional) Choose any Tags from the menu menu.
    4. 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:

    The targeting section, with the new segment called out.
    The targeting section, with the new segment called out.