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


Setting user attributes

Read time: 3 minutes
Last edited: Nov 11, 2021


This topic explains what user attributes are, how they impact what you see in LaunchDarkly, how to configure them, and how LaunchDarkly uses them to calculate and display flag settings for users.

Understanding user attributes

Users are people, services, machines, or other resources that encounter feature flags in your app. Any identifier that uniquely corresponds to a target can be designated as a user.

A more precise way to refer to one user is as a user object. A user object is a collection of a user's built-in and custom user attributes, identified by a user key.

LaunchDarkly provides built-in attribute fields for you to fill in, but 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.

All built-in user attributes are strings with the exception of anonymous:

Attribute KeyAttribute Example ValueNote
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""This attribute should be a valid IP address.
name"Jill Jones"
avatar"http://example.com/avatar.png"This attribute must be an absolute URL to an avatar image for the user. The avatar appears on the Users page.
anonymous"true"This can be a Boolean or string value. This attribute prevents the user from appearing on the dashboard. If the anonymous attribute is set to any value other than boolean false or null, LaunchDarkly treats the user as anonymous.
os25This attribute is available only in mobile SDKs. The mobile SDK automatically provides a value for the attribute.
device"Pixel XL marlin"This attribute is available only in mobile SDKs. The mobile SDK automatically provides a value for the attribute.

The user key is the only mandatory user attribute. All other user attributes are optional.

You can view a user's attributes by clicking on the individual user from the Users dashboard.

Viewing and managing users

By default, all of the attributes in your user objects are sent to LaunchDarkly. This data lets LaunchDarkly calculate the current flag settings for users and powers the autocomplete functionality throughout the LaunchDarkly UI.

Access user pages from the Users dashboard. To learn more, read The Users dashboard.

A user's page.
A user's page.

The SDK does not use the attributes on the Users dashboard to evaluate flags

The SDK only evaluates flags based on the user object you provide. The SDK does not use the attributes shown on the dashboard, and user attributes are not synchronized across SDK instances. You must provide all applicable user attributes for your targeting rules to apply correctly.

Creating private user attributes

You may not want to send all attributes back to LaunchDarkly. The security or data protection requirements of your organization may require you to limit what customer or user data is transmitted from your service to a third-party platform like LaunchDarkly.

For example, you may want to target customers by their personally identifying information (PII), such as their email address, without sending the email address to LaunchDarkly.

LaunchDarkly's private user attributes feature lets you choose which attributes get sent back to LaunchDarkly without sacrificing the ability to target user segments. This lets you create targeting rules and segments based on the attributes without having to send sensitive data back to LaunchDarkly.

Configuring private attribute settings in your SDK

There are three different ways to configure private attributes:

  • You can mark all attributes private globally in the LDClient configuration object.
  • You can mark specific attributes private by name globally in the LdClient configuration object.
  • You can mark specific attributes private by name for individual users when you construct LDUser objects.

User keys cannot be marked private.

If you initially mark an attribute as private, LaunchDarkly will continue to treat the attribute as private in subsequent evaluations as long as the user is on the dashboard, even if you later remove the "private" designation from the attribute. If you no longer want LaunchDarkly to treat the attribute as private, remove the "private" designation, delete the user from the Users dashboard, and re-evaluate the user.

To learn more about setting these configuration options, read your SDK's documentation.

Implications of using private attributes

If a feature flag contains targeting rules that reference private attributes, the user page may not be able to calculate flag settings for your users. The Users page indicates when it is unable to calculate flag settings because of private attributes. LaunchDarkly cannot perform autocomplete attributes you have made private.

Setting custom user attributes

Custom attributes contain any other user data that you would like to use to conditionally target your users. You can provide custom attributes in the user object.

The value of a custom attribute can be of the following types:

  • boolean
  • number
  • string
  • array

If you set the value of a custom attribute to a JSON object, it won't appear on your Users dashboard.

Here is an example user object which contains custom user attributes:

3"firstName": "Bob"
5 "groups":[
8 ]
9 }