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

EDIT ON GITHUB

Targeting users with flags

Read time: 10 minutes
Last edited: Jan 25, 2022

Overview

This topic explains how to use a flag's Targeting tab to control which users see a variation of a feature flag. Configuring which users see which variation of a flag is referred to as a flag's targeting.

You can use the Targeting tab to roll features out for internal testing, private betas, or usability tests before performing a broader rollout. You can even set expiration dates for flag targeting if you know you only want users to see a flag for a specific period of time.

While the Targeting tab uses the language of targeted "users", a user can be any identifier that uniquely corresponds to a target. You can target users of your application, email addresses, systems, services, machines, resources, or anything else that can be uniquely identified.

Assigning users to a variation

The "Target individual users" section of the targeting tab allows you to assign individual users to a particular flag variation.

Only target small numbers of users individually

We recommend using individual user targeting for very small numbers of individual users. Targeting more than 10,000 users individually may cause performance degradation, because the SDK takes longer to initialize when the targeting rules payload is large. To learn more about targeting many users, read Creating targeting rules.

If your application is already sending data back to LaunchDarkly, you can search for users by name, email address, or user key. These strings are case sensitive. Hover over the user row to see more attributes for that user.

If you need to target a user that LaunchDarkly doesn't know about, you can enter their key manually. These users display in yellow until they encounter a feature flag.

In the screenshot below, we see which users are seeing the first variation of a flag. That flag is targeted to them. This means that these users will see that flag variation when they access the flag.

A flag with users targeted.
A flag with users targeted.

Removing targeted users

You can remove a user from a flag's targeting list by clicking the user's name. To do this:

  1. Navigate to the flag's Targeting tab.
  2. In the "Target individual users" section, find the name of the user you wish to remove.
  3. Click the X next to their name to remove them:
A user in the flag's targeting section, with the X to remove called out.
A user in the flag's targeting section, with the X to remove called out.

Scheduling removal dates for user targeting

Scheduling removal dates is a Pro and Enterprise feature

Scheduling removal dates is available to customers on a Pro or Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

You can schedule a removal date and time for each individual user who is targeted by a flag. By doing this, you can specify a future date and time after which the user will no longer be targeted for the specific flag. You can do this when you add a new user, or for existing user targets.

This is useful if you want to give users trial access to a feature, run a controlled beta test, or just keep your flags organized by not having too many flags working at once.

You can also schedule a user to be removed from a segment, rather than from flag targeting. To learn more, read Scheduling user removal from segments.

To schedule a removal date for a user target:

  1. Navigate to the flag dashboard and select the flag for which you want to configure a removal date. The flag's Targeting tab appears.
  2. In the "Target individual users" section, search for the new user you want to target or click the name of an existing user you want to set a removal date for.
  3. Click Add + schedule Removal next to the user's name.
The user targeting field with the "Add + Schedule Removal" option called out.
The user targeting field with the "Add + Schedule Removal" option called out.
  1. In the "Remove user on" section, click never to expand a calendar view.
  2. Set a date and time for the user to be removed from the flag:
The calendar picker to schedule the user removal.
The calendar picker to schedule the user removal.
  1. Click Apply.
  2. Click Save changes, or if approvals are required for your environment, click Request approval.

The user targets are now scheduled for removal on the date and time you specified.

Creating targeting rules

In addition to targeting individual users, LaunchDarkly lets you target segments of users by constructing targeting rules.

Rules can have one or more conditions. Each condition has three parts:

  • An attribute, which defines the scope of the condition's impact, such as only targeting an email address.
  • 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.
  • A value, which identifies the attribute by a value you specify, such as gmail.com.

For example, 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 dropdown.
  4. Choose ends with from the operator dropdown.
  5. Enter gmail.com in the Enter some values field.
  6. Choose true from the serve dropdown.
  7. Click Save at the top of the Targeting screen to apply the rule.

Here is an image of the user targeting rule:

A user targeting rule.
A user targeting rule.

If a targeting rule references any custom attributes with null values, then the flag skips that rule.

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.

Targeting users based on custom attributes

LaunchDarkly allows you to target users based on arbitrary custom attributes, which means you can control who sees features based on any criteria that you send to us.

Custom attributes and built-in attributes

Setting a custom attribute with the same key as one of the built-in attributes will cause the attribute to be ignored during feature flag evaluation. For mobile SDKs, the custom attributes os and device are automatically included with os and device data. You can override this by specifying them as custom attributes in your user object and setting your own values.

As an example, here is a custom rule with two conditions. This rule serves true to users who are not in the segment Test Segment and whose Account attribute does not start with test.

Here is an image of the rule with conditions:

A rule serving "true" to users affected by two conditions.
A rule serving "true" to users affected by two conditions.

When you've finished setting up the conditions for your rule, you can decide whether your users will receive one variation, or a percentage rollout across several variations.

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
user is in segment, user is not in segmentsegment namesuser is included or excluded by the targeting rules for the named segments. Read more about 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, though LaunchDarkly allows you to omit the PATCH version. For example, `2.0` is a valid semantic version.

Server-side SDKs must be the following minimum version or higher to support sematic versioning:

  • .NET: 3.6.1
  • Apex: all versions
  • C/C++: all versions
  • Erlang: all versions
  • Go: v3
  • Java: 2.6.0
  • Haskell: all versions
  • Lua: all versions
  • Node.js: all versions
  • PHP: 2.5.0
  • Node: 3.4.0
  • Python: 4.3.0
  • Ruby: 2.5.0
  • Rust: 1.0.0-beta.1

No updates are required for client-side SDKs.

Date comparisons

Dates specified in the user object must be formatted in UNIX milliseconds: UNIX epoch * 1000. To learn more about UNIX date formatting, or convert a date and time to UNIX milliseconds read Current Millis.

Built-in attributes

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

  • key
  • firstName
  • lastName
  • email
  • avatar

The user key is the only mandatory user attribute. The JavaScript and React Web SDKs automatically generate a random key for you if you do not provide one.

All other user attributes are optional. For a full list of built-in user attributes, read Understanding user attributes.

LaunchDarkly does not automatically populate built-in attributes

While LaunchDarkly provides built-in attribute fields for you to fill in, the SDK does not automatically collect any information. The exceptions to this are the os and device attributes used by mobile SDKs. If you want to target your users based on any other built-in attributes, you must supply their values.

Maintaining user experience across anonymous and logged-in states

To associate pre-login (anonymous) behaviors with post-login (known) 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. The steps to make this happen are as follows:

  • 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 "uniqueId".
  • While the user is logged in, set the user's key to their real (primary) user key, but continue to use to use the unique identifier stored in the cookie as the users "uniqueId" custom attribute.
  • 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.

Example: custom attribute targeting

In this example, you will turn on a feature for a group of external beta testers. First, ensure that our back end sends a custom attribute called groups that identifies users that should be in the beta_testers group.

Here's how:

import (
"gopkg.in/launchdarkly/go-sdk-common.v2/lduser"
"gopkg.in/launchdarkly/go-sdk-common.v2/ldvalue"
)
user := lduser.NewUserBuilder("foo@example.com").
Custom("groups", ldvalue.String("beta_testers"))

To learn more, read UserBuilder, ldvalue.

Next, add a new rule on the Targeting tab. Set the attribute name to groups, the operator to is one of, the attribute value to beta_testers, and the name of your group of beta testers.

Any users in the beta_testers group now see the new dashboard feature. You have also kept the feature on for your internal tester Ernesto, since there's still an Include rule for him.

Percentage rollouts

If you want to do a percentage rollout, select "percentage rollout" from the dropdown and allocate users accordingly.

Here is an image of the percentage rollout screen:

The percentage rollout screen.
The percentage rollout screen.

In this example, 25% of the beta_testers group see the new dashboard feature.

Experiment allocation

If you're using Experimentation, experiment allocation allows you more flexibility when selecting your experiment population and ensures accurate experiment results. To learn how to enable and use experiment allocation, read Allocating experiment traffic.

Percentage rollout logic

When you set up a percentage rollout, the variation a user receives is determined by the user's key. The percentage rollout logic generates a hash from the user's key or attribute, the user's secondary attribute (if provided), the flag's key, and a hidden salt attribute stored in the flag.

The SDK uses this hash to generate a percentage value for that user. That value, compared to the value set for the percentage rollout value, determines which variation a user receives. The hash has partitions from 1 to 100,000. When you assign flag variations, the hash assigns values from 1 to 100,000 to users in each partition, in order. For example, when you assign 50% to variation A, LaunchDarkly serves variation A to hash partitions from 1 to 50,000.

A common use case for percentage rollouts is to increment the percentage of users targeted by a flag over time until 100% of the users see one variation of a flag. When you change the percentage allocation of users to flag variations, those users are reassigned different flag variations based on their partition's position in the 1 to 100,000 hash list. For example, if you change the percentage of users seeing variation A from 50% to 70%, partitions 50,001 to 70,000 would be added to the set of partitions already seeing variation A.

To learn more about rollouts and variation assignments, read Rollouts.

Advanced Targeting: Percentage rollout variation assignment by attribute

In the "Advanced" area of the percentage rollout menu, you can assign variation buckets to users based on any attribute sent to LaunchDarkly. For example, you can roll out a feature to 20% of companies, whereby users will be assigned to a variation bucket based on the value of their company attribute. This ensures that LaunchDarkly treats all users with matching attribute-value pairs the same. If you choose a custom attribute for this purpose, it should have either string values or integer numeric values. For users with a custom attribute number that includes a fraction or has a value type besides string or number, the variation bucket assignment is undefined.

Default rule: targeting remaining users

LaunchDarkly defines a final default rollout rule for any users that don't match any of the previous sections 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 screen:

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.

Conducting a Simple Rollout

If you do not want to target users based on user key or any custom attributes, you can simply use the default rule to control the flag's rollout for all users.

Setting the Off variation

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

If you do not specify an 'off' variation, then LaunchDarkly will return the Fallback variation defined in your code.

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" modal:

The "Convert to segment" modal.
The "Convert to segment" modal.

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