LaunchDarkly Developer Documentation

Get started in under 30 minutes.
LaunchDarkly provides feature flags as a service for Java · Python · Ruby · Go · Node.js · PHP · .NET. Control feature launches -- who sees what and when -- without multiple code deploys. Easy dashboard for phased rollouts, targeting and segmenting.
Need more help? write us at support@launchdarkly.com

Get Started    

Targeting users

The Targeting tab lets you determine which users see each variation of a feature flag. You can use the Targeting tab to roll features out for internal testing, private betas, or usability tests before performing a broader rollout. Let's walk through some examples.

Assigning users to a variation

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

To assign a single user to a variation, add the user to the corresponding variation. If your application is already sending data back to LaunchDarkly, you'll be able to search for users by name or e-mail address in addition to the key. By hovering over the user card, you can see other attributes for the user.

If you need to assign a user that LaunchDarkly doesn't know about, you can enter their key.

Here, we've turned the "new dashboard" feature on for our internal tester Ernesto by assigning him to the true variation.

Targeting rules based on user attributes

In addition to targeting individual users, LaunchDarkly allows you to target segments of users by constructing rules. Each rule has three parts: an attribute, an operator, and a user value.

For example, let's build a rule that targets all users whose e-mail address ends with gmail.com:

LaunchDarkly supports the following operators:

Operator
Attribute type
Meaning

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

LaunchDarkly includes some useful built-in attributes for users. All of them are strings with the exception of anonymous:

Attribute Key
Attribute Example Value
Note

key

"1f2e2d3a"

Required for evaluation. This should be unique for each user.

secondary

"2398127"

If provided, this attribute is incorporated into generating a variation in percentage rollouts.

ip

"10.10.10.10"

email

"user@example.com"

name

"Jill Jones"

firstName

"Jill"

lastName

"Jones"

country

"Uganda"

anonymous

true

Boolean type

Anonymous users

You will still need to generate a unique key for anonymous users-- session IDs or UUIDs work best for this.

Anonymous users work just like regular users, except that they won't appear on your Users page in LaunchDarkly. You also can't search for anonymous users on your Features page, and you can't search or autocomplete by anonymous user keys. This is actually a good thing-- it keeps anonymous users from polluting your Users page!

LaunchDarkly allows you to target users based on arbitrary custom attributes-- meaning 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.

You can add multiple conditions to a rule. 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.

Here, we've created a custom rule with two conditions (Custom Rule #1). This rule serves true to all users whose e-mail address ends with gmail.com and whose country is either USA or CANADA.

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.

Let's turn a feature on for a group of external beta testers. First, we need to ensure that our backend sends a custom attribute called groups that identifies users that should be in the beta_testers group:

 LDUser user = new LDUser.Builder("foo@example.com")
   .custom("groups", "beta_testers")   
   .build()
 
user = {"key" : "foo@example.com", "custom": {"groups": "beta_testers}}
user = {:key => "foo@example.com", :custom => {:groups => "beta_testers"}}
var custom = make(map[string]interface{})
custom["groups"] = "beta_testers"
user = User {
 Key: "foo@example.com",
 Custom: custom,
}
var user = {"key" : "foo@example.com", "custom" : {"groups": "beta_testers"}}
$user = new LDUser("foo@example.com", null, null, null, ["groups" => "beta_testers"]);
       

On the Targeting tab, we add a new rule, set the attribute name to groups, the operator to is one ofand enter beta_testers, the name of our group of beta testers.

That's it! Any users in the beta_testers group will see the new dashboard feature. We've also kept the feature on for our internal tester Ernesto, since there's still an Include rule for him.

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

Now, 25% of our beta_testers will see the new dashboard feature.

Advanced Targeting: Percentage rollouts bucketed by attribute

In the Advanced area of a percentage rollout, you can bucket users by any attribute sent to LaunchDarkly. For example, you can roll out a feature to 20% of companies, whereby users will be bucketed by the value of their company attribute. This ensures that every user with a matching attribute-value pairing is treated consistently.

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.

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 kill switch 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, we have two custom rules: Rule #1 and Rule #2. Rules are evaluated top down, so in this example, Rule #1 is evaluated before Rule #2. If a user matched both rules, Rule #1 would take priority.

Bulk user targeting

The 'Bulk Edit' button lets you manage all of your user targets for a single feature flag variation. Clicking 'Bulk Edit' (or hitting Ctrl-V to paste a list of users into the Add users field) will open a modal that allows you to add, remove, or replace user targets for the current variation.

In this example, we are bulk editing the true variation by adding 8 new users to target. Users that are already targeted will appear greyed out.

Using the dropdown, you can select one of three actions: "Add", "Remove", or "Replace".

  • Add - Adds the selected users as targets to the variation
  • Remove - Removes the selected users from the target variation
  • Replace - Replaces all currently targeted users with the selected users

In the left text area, you may paste or type user keys or e-mails as comma separated values (CSV), one per line or separated by a comma. You may paste hundreds of user keys or e-mail addresses at once. Once you're finished, LaunchDarkly will look up users by key or e-mail and display them in the right panel.

  • All Represents all of the users that may be impacted by the action, whether they are added or removed. The checkbox must be checked for the user in order for the action to apply.
  • Represents inputed user keys that currently match users in the system. For example, if you enter the user key bob@example.com, and bob@example.com already exists in LaunchDarkly, he will show up in this list.
  • ? Represents users with no matching records in LaunchDarkly. If you are adding users, and these users do not currently exist in LaunchDarkly, they will be added to the targeting list.
  • ! Represents user key inputs with multiple matching records. For example, if you enter the e-mail address bob@example.com, but there are multiple user keys that have bob@example.com as an email address, then the system may return multiple matching records. You can select the correct record by toggling the checkbox.
  • Current Lists all of the currently targeted users for the variation.

Targeting users