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    Documentation

Targeting users

Overview

This topic explains how to use a flag's Targeting tab to control which users or targets see a 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.

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.

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, two users are seeing the true variation of the "Show new dashboard" flag. That flag is targeted to them. This means that these users will see the new dashboard when they access it.

The "Show new dashboard" flag with two users targeted.

The "Show new dashboard" flag with two users targeted.

Targeting rules based on user attributes

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

Each rule has three parts:

  • an attribute, which defines the scope of the flag's impact, such as only impacting an email address
  • an operator, which sets differentiating characteristics of the attribute, such as limiting the attribute to emails that end with a certain extension
  • a user value, which identifies a user or resource by a value you specify, such as gmail.com.

For example, let's define a rule that serves true to all users whose e-mail address ends with gmail.com.

To write this rule, we specify the attribute as email, the operator as ends with, and the user value as gmail.com. Remember to click Save Changes to apply the rule.

A user targeting rule.

A user targeting rule.

Operators

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

user is in segment, user is not in segment

segment names

user 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 (<=)

string

Semantic version comparison. Valid string attributes must follow the semantic versioning specification, though we allow the PATCH version to be omitted (so that, e.g. 2.0 is considered a valid semantic version).

Scheduling feature flags

LaunchDarkly does not have a built in way to schedule a flag for a particular date, but you can achieve this with targeting rules.

For example, you may want to serve true to show your feature, but only after November 19th, 2018.

Date Comparisons

Dates require UNIX formatting

Dates specified in the user object should 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.

Required SDK versions for semantic versions

Older versions of our server SDKs do not support semantic version operators. Minimum SDK versions are:

Go: v3
Node: 3.4.0
Python: 4.3.0
Ruby: 2.5.0
.NET: 3.6.1
Java: 2.6.0
PHP: 2.5.0

No updates are required for Android, iOS, or JavaScript.

Built-in attributes

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 used with a user's key to generate 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

We do not provide built-in attributes

While we provide all of these fields for you to fill in, the SDK does not automatically collect any information. If you want to target your users based on any of these attributes you must supply their values.

Anonymous users

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!

Note that anonymous users will still count toward your monthly active user limit.

Maintaining 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.
• until the user logs in, use this unique identifier as both the user’s key, and a custom attribute. The custom attribute could be named anything, but for this example it is named "uniqueId".
• while the user is logged in, set the users 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 at least those that may effect logged out users), use the advanced option for all percentage rollouts to do rollouts based on the "uniqueId" custom attribute.

Secondary attribute

The secondary attribute is a special attribute that the SDKs incorporate into the bucketing hash automatically when it is included in your user object. Unlike other attributes, you cannot use the secondary attribute in targeting rules.

Targeting users based on custom attributes

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.

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.

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

Percentage Rollouts

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

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

Percentage rollout logic

When you set up a percentage rollout, the variation a user receives is determined by the user's key. When a percentage rollout is evaluated, it generates a hash from the user's key, the user's secondary attribute if available, and a hidden salt attribute stored in the flag. The SDK then 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.

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.

If you choose a custom attribute for this purpose, it should have either string values or integer numeric values. For any user where the value of the custom attribute is a number with a fractional component, or a value of any other type besides string and number, the bucketing result 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.

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

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

User Storage

The LaunchDarkly dashboard user page shows only cached user information. The user data is evicted after 30-days if a user has not been seen by LaunchDarkly for more than 30 days. The rational behind this is that the system should be regularly calling variations on users which would cause them to appear in the dashboard through normal usage.

If the variations are being called less frequently than 30 days, the best solution would be to manually identify all of the users that you wish to be kept in the dashboard every 30 days.



Targeting users


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.