• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

User configuration

Read time: 36 minutes
Last edited: Jun 18, 2021

Overview

This topic explains how to configure user objects in LaunchDarkly SDKs. These features are available for both client-side and server-side SDKs.

Configuring user objects

Every LaunchDarkly SDK lets you configure user objects to return specific data to LaunchDarkly. Some SDKs let you designate anonymous users or configure users with private attributes.

Anonymous users don't appear on your Users page in the LaunchDarkly dashboard. You can't search for anonymous users on your Features page, and you can't search or autocomplete by anonymous user keys. If you use the same user key for every anonymous user, you also can't use percentage rollouts or Experimentation with anonymous users.

In client-side SDKs, if you don't provide a user key or set it to null, and set anonymous to true, then the SDK generates a random user key for you.

You can use private user attributes for targeting purposes, but these attributes are removed from user data sent back to LaunchDarkly.

Details about each SDK's configuration are available in the SDK-specific sections below.

  • Client-side SDKs
  • Server-side SDKs

Client-side SDKs

Here are the configuration options for user entities in client-side SDKs.

Android

Feature flag targeting and rollouts are determined by the user you pass to your client. In the Android SDK, we use a builder pattern to construct users. Here's an example:

1LDUser user = new LDUser.Builder("aa0ceb")
2 .email("fake@example.com")
3 .firstName("Jake")
4 .lastName("Fake")
5 .custom("group", "microsoft")
6 .build();

The first argument to the builder is the user's key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most of our built-in attributes like names and email addresses expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans, or numbers. If you enter a custom value on our dashboard that looks like a number or a boolean, the value is interpreted as one. The Android SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Private user attributes in the Android SDK

You can optionally configure the Android SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Android SDK you can define private attributes for the entire LaunchDarkly client. When creating the LDConfig object, call the setPrivateAttributeNames method, which which takes in a set of custom or built-in attributes as a parameter. If any user has a custom or built-in attribute named in this set, it is removed before the SDK sends the user to LaunchDarkly.

1HashSet<String> privateAttributes = new HashSet<>();
2privateAttributes.add("name"); // built-in attribute
3privateAttributes.add("group"); // custom attribute
4
5LDConfig ldConfig = new LDConfig.Builder()
6 .setPrivateAttributeNames(privateAttributes)
7 .build();

You can also mark attributes as private when building the user object by using the private versions of the builder methods to set the attributes. For example:

1LDUser user = new LDUser.Builder("aa0ceb")
2 .email("fake@example.com")
3 .privateName("Jane")
4 .privateCustom("group", "microsoft")
5 .build();

When this user is sent back to LaunchDarkly, the name and group attributes are removed.

Anonymous users in the Android SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUser user = new LDUser.Builder("user key")
2 .anonymous(true)
3 .build();

You can leave the key parameter in the Builder null or make it an empty string. The client will automatically set it to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

C/C++ (client-side)

Feature flag targeting and rollouts are determined by the user you pass to your client. Here's an example:

1struct LDJSON *attributes, *groups;
2groups = LDNewArray();
3LDArrayPush(groups, LDNewText("Google"));
4LDArrayPush(groups, LDNewText("Microsoft"));
5attributes = LDNewObject();
6LDObjectSetKey("groups", groups);
7struct LDUser *user = LDUserNew("aa0ceb");
8LDUserSetFirstName(user, "Jake");
9LDUserSetLastName(user, "Fake");
10LDUserSetCustomAttributesJSON(user, attributes);

The first argument to the builder is the user's key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data using custom attributes.

Custom attribute type interpretation

Most of our built-in attributes (like names and e-mail addresses) expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans or numbers. If you enter a custom value that looks like a number or a boolean, it is interpreted that way.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Private user attributes in the C/C++ SDK

You can optionally configure the C/C++ SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the C/C++ SDK there are two ways to define private attributes for the LaunchDarkly client:

  • When creating the LDConfig object, you can set the allAttributesPrivate value to true. When you do this, all user attributes except the key are removed before the SDK sends the user to LaunchDarkly.
  • When creating the LDConfig object, you can configure a map of privateAttributeNames. If any user has a custom or built-in attribute named in this list, it is removed before the SDK sends the user to LaunchDarkly.
1struct LDConfig *config = LDConfigNew("YOUR_MOBILE_KEY");
2// Mark all attributes private
3LDConfigSetAllAttributesPrivate(config, true);

Anonymous users in the C/C++ SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1struct LDUser *user = LDUserNew("aa0ceb");
2LDUserSetAnonymous(user, true);

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

Flutter

Feature flag targeting and rollouts are determined by the user you pass to your client. In the Flutter SDK, we use a builder pattern to construct users.

Here's an example:

1LDUser user = LDUserBuilder('aa0ceb')
2 .email('fake@example.com')
3 .firstName('Jake')
4 .lastName('Fake')
5 .custom('group', LDValue.ofString('microsoft'))
6 .build();

The first argument to the builder is the user's key. In this case, we've used the hash 'aa0ceb'. The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most of our built-in attributes like names and e-mail addresses expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans or numbers. Custom attribute values in the Flutter SDK use the LDValue class to support the various underlying types for the values. If you enter a custom value on our dashboard that looks like a number or a boolean, it is interpreted that way. The Flutter SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Private user attributes in the Flutter SDK

Optionally, you can configure the Flutter SDK to treat some or all user attributes as private user attributes. You can use private user attributes for targeting purposes. They are removed from the user data sent back to LaunchDarkly.

In the Flutter SDK, you can define private attributes for the entire LaunchDarkly client. When you create the LDConfig object, you can call the setPrivateAttributeNames method, which which takes in a set of custom or built-in attributes as a parameter. If any user has a custom or built-in attribute named in this set, it are removed before the SDK sends the user to LaunchDarkly.

1Set<String> privateAttributes =
2 { 'name' // built-in attribute
3 , 'group' // custom attribute
4 };
5
6LDConfig ldConfig = new LDConfigBuilder()
7 .setPrivateAttributeNames(privateAttributes)
8 .build();

You can also mark attributes as private when building the user object by using the private versions of the builder methods to set the attributes. For example:

1LDUser user = LDUserBuilder('aa0ceb')
2 .email('fake@example.com')
3 .privateName('Jane')
4 .privateCustom('group', LDValue.ofString('microsoft'))
5 .build();

When this user is sent back to LaunchDarkly, the name and group attributes are removed.

Anonymous users in the Flutter SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUser user = LDUserBuilder('user key')
2 .anonymous(true)
3 .build();

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

iOS

You can also pass optional properties to the user object:

1var user = LDUser(key: "YOUR_USER_KEY")
2user.name = "Human Person"
3user.email = "human@example.com"

Here, we added the user's full name and email address. To learn more about the specific user properties that are available in this SDK, read the SDK's API docs.

Private user attributes in the iOS SDK

You can optionally configure the iOS SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data the SDK sends to LaunchDarkly.

In the iOS SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • When creating the LDConfig object, you can set the allUserAttributesPrivate attribute to true.
  • When creating the LDConfig object, you can set the privateUserAttributes attribute to a list of user attribute names, such as ["name", "email"]. If any user has a custom or built-in attribute named in this list, it is removed before the SDK sends the user to LaunchDarkly.

You can also mark attributes as private on a particular LDUser instance, for example:

1var user = LDUser(key: "USER_KEY", name: "USER_NAME")
2user.privateAttributes = ["name"]

Anonymous users in the iOS SDK

You can also declare a LDUser to be an anonymous, not logged-in user:

1var user = LDUser(key: "USER_KEY")
2user.isAnonymous = true
3
4// Or have the SDK use a device persistent key. This sets `isAnonymous` by default.
5let user = LDUser()

You must generate a unique key for anonymous users. Session IDs or UUIDs work best for this.

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

JavaScript

Personally-identifying user keys

If the key attribute you rely on in your user JSON contains personally identifiable information, you should enable the useReport option by customizing your client . By default, flag settings are fetched by sending the user JSON as a JSON base64 URL-encoded path parameter. When useReport is enabled, flag settings will be fetched by sending the user JSON in the body of a REPORT request instead, thereby hiding that information from request logs.

Let's walk through the user JSON in more detail. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

Here's a more complete example of a user:

1var user = {
2 "key": "aa0ceb",
3 "firstName": "Ernestina",
4 "lastName": "Evans",
5 "email": "ernestina@example.com",
6 "custom": {
7 "groups": ["Google", "Microsoft"]
8 }
9};

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Besides the key, LaunchDarkly supports the following attributes at the "top level". All of these are optional:

  • ip: Must be an IP address.
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user's e-mail address. If an avatar URL is not provided, LaunchDarkly uses Gravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name.
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to built-in attributes, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most built-in attributes, like names and email addresses, expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans, or numbers. If you enter a custom value on our dashboard that looks like a number or a boolean, it is interpreted that way.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the JavaScript SDK

You can optionally configure the JavaScript SDK to treat all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

To mark all user attributes except the key as private in the JavaScript SDK, you can use the allAttributesPrivate option:

1var user = {
2 "key": "aa0ceb",
3 "name": "Grace Hopper",
4 "email": "gracehopper@example.com"
5};
6
7var ldclient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user, options = {
8 allAttributesPrivate: true
9});

In the above example, the name and email attributes are removed.

You can also specify an array of which attributes should be private with the privateAttributeNames option. You can configure this option on a per-user basis by specifying which attributes should be private in your user object.

In the example below, this option is configured in both the user object and the configuration object to demonstrate what this looks like:

1var user = {
2 "key": "aa0ceb",
3 "name": "Grace Hopper",
4 "email": "gracehopper@example.com"
5 "privateAttributeNames": ["email"]
6};
7
8var ldclient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user, options = {
9 privateAttributeNames: ["email"]
10});

In the example above, only the user's key and their name will be sent back to LaunchDarkly.

Parameters for JS SDK < 2.0

SDK versions earlier than 2.0 use snake case rather than camel case in the options object. private_attribute_names and all_attributes_private are the parameter names that should be used. privateAttributeNames is still valid when specified in the user object.

Anonymous users in the JavaScript SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1// Starting with version 2.10.0 of the JavaScript SDK, to create
2// an anonymous user you can specify the "anonymous" property and
3// omit the "key" property. In doing so, the LaunchDarkly client
4// will auto-generate a unique identifier for this user, and the
5// identifier will remain constant across browser sessions.
6var user = {"anonymous": true};
7
8// If you are using earlier SDK versions, you need to specify
9// the "key" property as earlier versions do not auto-generate the
10// property.
11//
12// Here you need to generate a unique key for anonymous
13// users. You can use the session ID or a UUID.
14//
15// We suggest storing the user's key in a cookie, otherwise you
16// might create a new user for each page request.
17var user2 = {"key":"aa0ceb", "anonymous": true};

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

Node.js (client-side)

Personally-identifying user keys

By default, when the SDK requests feature flags from LaunchDarkly, it makes an HTTP GET request with the user properties encoded in the URL. If you do not want user keys or other properties to be in request URLs, enable the useReport option in your client configuration. User data is sent in the body of an HTTP REPORT request instead.

Let's walk through the user JSON in more detail. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

Here's a more complete example of a user:

1const user = {
2 key: "aa0ceb",
3 firstName: "Ernestina",
4 lastName: "Evans",
5 email: "ernestina@example.com",
6 custom: {
7 groups: ["Google", "Microsoft"]
8 }
9};

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Besides the key, LaunchDarkly supports the following attributes at the "top level". All of these are optional:

  • ip: Must be an IP address.
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user's e-mail address. If an avatar URL is not provided, LaunchDarkly uses Gravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name.
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to built-in attributes, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most of our built-in attributes, like names and e-mail addresses, expect string values. Custom attribute values can be strings, booleans like true or false, numbers, or lists of strings, booleans or numbers. If you enter a custom value that looks like a number or a boolean, it is interpreted that way.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the Node.js SDK

You can optionally configure the JavaScript SDK to treat all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

To mark all user attributes except the key as private in the JavaScript SDK, you can use the allAttributesPrivate option:

1const user = {
2 key: "aa0ceb",
3 name: "Grace Hopper",
4 email: "gracehopper@example.com"
5};
6
7const ldClient = LaunchDarkly.initialize('YOUR_CLIENT_SIDE_ID', user, {
8 allAttributesPrivate: true
9});

In the above example, the name and email attributes are removed.

You can also specify an array of which attributes should be private with the privateAttributeNames option. You can configure this option on a per-user basis by specifying which attributes should be private in your user object.

In the example below, this option is configured in both the user object and the configuration object to demonstrate what this looks like:

1const user = {
2 key: "aa0ceb",
3 name: "Grace Hopper",
4 email: "gracehopper@example.com"
5 privateAttributeNames: ["email"]
6};
7
8const ldClient = LaunchDarkly.initialize('YOUR_CLIENT_SIDE_ID', user, {
9 privateAttributeNames: ["email"]
10});

In the example above, only the user's key and their name will be sent back to LaunchDarkly.

Anonymous users in the Node.js SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1// To create an anonymous user with an auto-generated key, specify
2// the "anonymous" property and omit the "key" property. The LaunchDarkly
3// client creates a unique key for this user and caches it locally.
4const user = { anonymous: true };
5
6// You can also specify any key you want:
7const user2 = { key: "aa0ceb", anonymous: true };

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

React

All user-related functionality provided by the JavaScript SDK is also available in the React SDK.

Unlike the JavaScript SDK, the React SDK does not require a user object for initialization. If one is not specified, the React SDK uses an anonymous user by default.

React Native

Here is a complete user configuration object utilizing all available fields:

1let user =
2 { key: '2fbfa269b78e24c8e967f482b89c939b',
3 name: 'grace_hopper',
4 firstName: 'Grace',
5 lastName: 'Hopper',
6 email: 'gracehopper@example.net',
7 anonymous: false,
8 privateAttributeNames: ['name'],
9 country: 'USA',
10 avatar: 'avatar',
11 ip: '192.0.2.1',
12 custom: {'groups': 'users'}
13 };

Let's walk through this code. The first key in the object is the user's key. In this case we've used the value 2fbfa269b78e24c8e967f482b89c939b. The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use any value such as a primary key, an e-mail address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other keys (like firstName, email, and the custom attributes) are optional. The attributes you specify will automatically appear on the LaunchDarkly application dashboard, meaning that you can start segmenting and targeting users with these attributes.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data using custom attributes, like the groups attribute in the example above. Custom attributes are one of the most powerful features of LaunchDarkly. They let you target users according to any data that you want to send to us, including organizations, groups, andaccount plans. Anything you pass to us becomes available instantly on your dashboard.

Private user attributes in the React Native SDK

Private attributes allow you to specify keys you do not want to send to the LaunchDarkly servers. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly. When this user is sent back to LaunchDarkly, the name attribute is removed.

Anonymous user attributes in the React Native SDK

The anonymous key lets you distinguish logged out or unregistered users while still using LaunchDarkly. Anonymous users work just like regular users, except that they do not appear on your Users page in LaunchDarkly. This keeps anonymous users from polluting your Users page.

You can't search for anonymous users on your Features page, and you can't search or autocomplete by anonymous user keys. If you use the same user key for every anonymous user, you also can't use percentage rollouts or Experimentation with anonymous users.

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

Roku

You can create a user object with:

1user = LaunchDarklyUser("my-user-key")

User objects can be customized with:

1user.setFirstName(String)
2
3user.setLastName(String)
4
5user.setEmail(String)
6
7user.setName(String)
8
9user.setAvatar(String)
10
11user.setCustom(AssociativeArray)

Private user attributes in the Roku SDK

Users can have specific fields marked as private with:

1user.addPrivateAttribute(String)

Anonymous users in the Roku SDK

Designate an anonymous user with:

1user.setAnonymous(Boolean)

Xamarin

Feature flag targeting and rollouts are determined by the user you pass to your Identify call. In the Xamarin SDK, you can construct a simple User that only has a key by calling User.WithKey, or use User.Builder which allows setting all properties. Here's an example:

1LDUser user = User.Builder("aa0ceb")
2 .FirstName("Ernestina")
3 .LastName("Evans")
4 .Email("ernestina@example.com")
5 .Custom("group", "admins")
6 .Build();

Let's walk through this snippet. The argument to Builder is the user's key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes (set by calls to FirstName, LastName, Email, and Custom attributes) are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to the built-in attributes defined in the User class, you can pass us any of your own user data by passing custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most of our built-in attributes, like names and email addresses, expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans, or numbers. If you enter a custom value on our dashboard that looks like a number or a boolean, the value is interpreted as one. The Xamarin SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the Xamarin SDK

You can optionally configure the Xamarin SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Xamarin SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • When creating the LaunchDarkly Configuration object, you can call the AllAttributesPrivate method, which takes in a boolean parameter. If true, all user attributes except the key for all users are removed before the SDK sends the user to LaunchDarkly.
  • When creating the LaunchDarkly Configuration object, you can call the PrivateAttributeName method, which takes in a string attribute nameas a parameter and adds it to an internally managed list of private attributes. This method may be called multiple times to mark additional attributes as private. If any user has a custom or built-in attribute named in the private attributes list, it are removed before the SDK sends the user to LaunchDarkly.

You can also mark attributes as private when building the user object by calling AsPrivateAttribute() immediately after setting the attribute. For example:

1var user = User.Builder("aa0ceb")
2 .Email("test@example.com").AsPrivateAttribute()
3 .Build();

When this user is sent back to LaunchDarkly, the email attribute is omitted.

Anonymous users in the Xamarin SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUser user = User.Builder("aa0ceb")
2 .Anonymous(true)
3 .Build();

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

We recommend using the same user key for every initialization and then replacing that with the actual user key when you know who the user is. This way LaunchDarkly counts the initialization user key only once against your MAU, instead of every time you initialize.

In Android or iOS, you can also allow the SDK to create a key for an anonymous user based on a unique device identifier as defined by the DeviceInfo Xamarin plugin. It will do so if you set the key to null and set the anonymous flag:

1LDUser user = User.Builder((string)null).Anonymous(true).Build();

Server-side SDKs

Here are the configuration options for user entities in server-side SDKs:

.NET

Feature flag targeting and rollouts are determined by the user you pass to your variation calls. In the .NET SDK, the User class has a WithKey method for creating a simple user with only a key, and a Builder method for building a user with other properties. Here's an example:

Here's an example:

1LDUser user = User.Builder("aa0ceb")
2 .FirstName("Ernestina")
3 .LastName("Evans")
4 .Email("ernestina@example.com")
5 .Custom("groups", LdValue.ArrayOf(LdValue.Of("Google"), LdValue.Of("Microsoft")))
6 .Build();

Let's walk through this snippet. The argument to Builder is the user's key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes (set by calls to FirstName, LastName, Email, and Custom attributes) are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to the built-in attributes defined in the User class, you can pass us any of your own user data by passing custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most of our built-in attributes, like names and email addresses, expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or objects. The SDK uses the LdValue type to represent arrays and objects. If you enter a custom value that looks like a number or a boolean, it is interpreted that way. The .NET SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the .NET SDK

You can optionally configure the .NET SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the .NET SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • When creating the LaunchDarkly Configuration object, you can configure Events Events with AllAttributesPrivate, which takes in a boolean parameter. If true, all user attributes except the key for all users are removed before the user is sent to LaunchDarkly.
  • Or, you can can configure Events with PrivateAttributes, which takes in a list of specific UserAttribute names. If any user has a custom or built-in attribute named in the private attributes list, it will be removed before the SDK sends the user to LaunchDarkly.

You can also mark attributes as private when building the user object by calling AsPrivateAttribute() after setting the attribute on the user builder. For example:

1var user = User.Builder("aa0ceb")
2 .Email("test@example.com").AsPrivateAttribute()
3 .Build();

When this user is sent back to LaunchDarkly, the email attribute is omitted.

Anonymous users in the .NET SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1var user = User.Builder("aa0ceb")
2 .Anonymous(true)
3 .Build();

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

Apex

Feature flag targeting and rollouts are determined by the user you pass to your variation calls.

1LDUser user = new LDUser.Builder('aa0ceb')
2 .setFirstName('Ernestina')
3 .setLastName('Evans')
4 .setEmail('ernestina@example.com')
5 .setCustom(new LDValueObject.Builder()
6 .set('groups', new LDValueArray.Builder()
7 .add(LDValue.of('Google'))
8 .add(LDValue.of('Microsoft'))
9 .build()
10 )
11 .build()
12 )
13 .build();

Let's go through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Anonymous users in the Apex SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUser user = new LDUser.Builder('abc123')
2 .setAnonymous(true)
3 .build();

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

Private user attributes in the Apex SDK

Optionally, you can configure the Apex SDK to treat some or all user attributes as private user attributes. You can use private user attributes for targeting, but they are redacted from the user data sent back to LaunchDarkly.

In the Apex SDK there are two ways to define private attributes for the LaunchDarkly client:

  • When creating the LDConfig object, you can use setAllAttributesPrivate(true). When you do this, all user attributes (except the key) for the user are redacted before the SDK sends the user to LaunchDarkly.
1LDConfig config = new LDConfig.Builder()
2 .setAllAttributesPrivate(true)
3 .build();
  • You can also define private attribute names on a per-user basis. For example:
1Set<String> privateAttributes = new Set<String>();
2privateAttributes.add('firstName');
3
4LDUser user = new LDUser.Builder('aa0ceb')
5 .setFirstName('alice')
6 .setPrivateAttributeNames(privateAttributes)
7 .build();

C/C++ (server-side)

Feature flag targeting and rollouts are determined by the user you pass to your variation calls.

1struct LDUser *user = LDUserNew("aa0ceb");
2LDUserSetFirstName(user, "Ernestina");
3LDUserSetLastName(user, "Evans");
4LDUserSetEmail(user, "ernestina@example.com");
5
6struct LDJSON *tmp;
7struct LDJSON *custom = LDNewObject();
8struct LDJSON *groups = LDNewArray();
9tmp = LDNewText("Google");
10LDArrayPush(groups, tmp);
11tmp = LDNewText("Microsoft");
12LDArrayPush(groups, tmp);
13LDObjectSetKey(custom, "groups", groups);
14
15LDUserSetCustom(user, custom);

Let's walk through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

1LDUserFree(user);

When you are done with an LDUser ensure that you free the structure.

Private user attributes in the C/C++ SDK

You can optionally configure the C/C++ SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the C/C++ SDK there are three ways to define private attributes for the LaunchDarkly client:

  • When creating the LDConfig object, you can use LDConfigSetAllAttributesPrivate. When you do this, all user attributes (except the key) for the user are removed before the SDK sends the user to LaunchDarkly.
1LDConfigSetAllAttributesPrivate(config, true);
  • When creating the LDConfig object, you can list specific private attributes with LDConfigAddPrivateAttribute. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.
1LDConfigAddPrivateAttribute(config, "email");
  • You can also define private attribute names on a per-user basis. For example:
1LDUserAddPrivateAttribute(user, "email");

Anonymous users in the C/C++ SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUserSetAnonymous(user, true);

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

Erlang

Feature flag targeting and rollouts are determined by the user you pass to your variation calls.

Map = #{
    key => <<"aa0ceb">>,
    secondary => <<"abc">>,
    ip => <<"198.51.100.0">>,
    country => <<"your-country">>,
    email => <<"foo@bar.com">>,
    first_name => <<"a">>,
    last_name => <<"z">>,
    avatar => <<"ratavA">>,
    name => <<"foobar">>,
    anonymous => false,
    <<"custom-key">> => <<"custom-value">>
},
User = ldclient_user:new_from_map(Map)
The user key is mandatory

The most important attribute in the example above is the user key. The user key should be unique to each user. In the example above, we used the binary "aa0ceb". You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data as key-value pairs in the map, like the CustomKey in the example above. Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Anonymous users in the Erlang SDK

Key = <<"aa0ceb">>,
Anonymous = true,
Map = #{
    key => Key,
    anonymous => Anonymous,
},
User = ldclient_user:new_from_map(Map)

You must still generate a unique key for anonymous users. We recommend using Session IDs or UUIDs.

Private user attributes in the Erlang SDK

You can configure the Erlang SDK to treat some or all user attributes as private user attributes. You can use private user attributes to target users without sending data associated with that user back to LaunchDarkly.

To learn more about private user attributes, read Setting user attributes.

When you create the Options map, use the private_attributes key to set private user attributes. When you do this, the SDK does not send the user attributes you specify to LaunchDarkly.

The SDK always sends the user key
The user key is not optional. You cannot set it as a private user attribute.
ldclient:start_instance("YOUR_SDK_KEY", my_instance, #{private_attributes => [email]})

Go

Feature flag targeting and rollouts are determined by the user you pass to your Variation calls. The Go SDK defines a User struct and a UserBuilder to make this easy. Here's an example:

1import (
2 "gopkg.in/launchdarkly/go-sdk-common.v2/lduser"
3 "gopkg.in/launchdarkly/go-sdk-common.v2/ldvalue" // for custom attributes - see below
4)
5
6// User with only a key
7user1 := lduser.NewUser("user1-key")
8
9// User with a key plus other attributes
10user2 := lduser.NewUserBuilder("user2-key").
11 FirstName("Ernestina").
12 LastName("Events").
13 Email("ernestina@example.com").
14 Custom("groups", ldvalue.ArrayOf(
15 ldvalue.String("Google"), ldvalue.String("Microsoft"))).
16 Build()

The most common attribute is the user's key. In this case we used the strings "user1-key" and "user2-key". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away. The documentation for User and UserBuilder shows all of the available attributes.

Custom attribute type interpretation

Most of our built-in attributes (like names and e-mail addresses) expect string values. Custom attributes values can be strings, booleans (like true or false), numbers, or arrays or maps containing any of type of value supported by JSON.

In SDK versions 4.16.0 and later, these types are all represented by the ldvalue.Value type; earlier versions use the catch-all Go type interface{}.

If you enter a custom value that looks like a number or a boolean, it is interpreted that way. The Go SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Private user attributes in the Go SDK

You can optionally configure the Go SDK to treat some or all user attributes as Private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Go SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • You can set the configuration option AllAttributesPrivate to true. If this is enabled, all user attributes (except the key) for all users are removed before the SDK sends the user to LaunchDarkly.
  • You can set the configuration option PrivateAttributeNames to a list of attribute names. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.
1import (
2 ld "gopkg.in/launchdarkly/go-server-sdk.v5"
3 "gopkg.in/launchdarkly/go-server-sdk.v5/ldcomponents"
4)
5
6var config ld.Config
7
8// Make all attributes private for all users
9config.Events = ldcomponents.SendEvents().AllAttributesPrivate(true)
10
11// Or, make just the name and email attributes private for all users
12config.Events = ldcomponents.SendEvents().
13 PrivateAttributeNames(lduser.NameAttribute, lduser.EmailAttribute)

You can also define a set of private attributes on the user object itself. In this example, Email is private for this user (in addition to any private attributes that were specified globally):

1import (
2 "gopkg.in/launchdarkly/go-sdk-common.v2/lduser"
3)
4
5user := lduser.NewUserBuilder("user-key").
6 FirstName("Ernestina").
7 LastName("Events").
8 Email("ernestina@example.com").AsPrivateAttribute().
9 Build()

Anonymous users in the Go SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1import (
2 "gopkg.in/launchdarkly/go-sdk-common.v2/lduser"
3)
4
5// Anonymous user with only a key
6user1 := lduser.NewAnonymousUser("user1-key")
7
8// Anonymous user with a key plus other attributes
9user2 := lduser.NewUserBuilder("user2-key").
10 Anonymous(true).
11 Country("US").
12 Build()

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

Haskell

Feature flag targeting and rollouts are determined by the user you pass to your variation calls.

1{-# LANGUAGE OverloadedStrings #-}
2
3import LaunchDarkly.Server.User
4
5import Data.Function ((&))
6
7user :: User
8user = (makeUser "aa0ceb")
9 & setFirstName "Ernestina"
10 & setLastName "Evans"
11 & setEmail "ernestina@example.com"

The most important attribute in the example above is the user key. The user key is mandatory.

In the example above, we used the hash "aa0ceb".

The user key should be unique to each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes like names and email addresses, you can pass any of your own user data as custom attributes, like the groups attribute in the example above. Custom attributes are one of LaunchDarkly's most powerful features. They let you target users according to any data that you want to send, including organizations, groups, and account plans. Anything you pass to us becomes available instantly on our dashboard.

Private user attributes in the Haskell SDK

Optionally, you can configure the Haskell SDK to treat some or all user attributes as private user attributes. You can use private user attributes for targeting purposes without sending data about the user associated with them back to LaunchDarkly.

To learn more about private user attributes, read Setting user attributes.

When you create the Config object, use configSetAllAttributesPrivate to set all user attributes as private. When you do this, all user attributes (except the key) are removed before the SDK sends the user to LaunchDarkly.

1config' = configSetAllAttributesPrivate True config

When you create the Config object, you can list specific private attributes with configSetPrivateAttributeNames. If any user has a custom or built-in attribute named in this list, it is removed before the SDK sends the user to LaunchDarkly.

1import Data.Set (fromList)
2
3config' = configSetPrivateAttributeNames (fromList ["email"]) config

You can also define private attribute names on a per-user basis.

For example:

1import Data.Set (fromList)
2
3user' = userSetPrivateAttributeNames (fromList ["email"]) user

Anonymous users in the Haskell SDK

You can distinguish logged-in users from anonymous users in the SDK.

1user` = userSetAnonymous True user

You still must generate a unique key for anonymous users. Session IDs or UUIDs work best for this.

Java

Feature flag targeting and rollouts are determined by the user you pass to your variation calls. In the Java SDK, we use a builder pattern to construct users. Here's an example:

1LDUser user = new LDUser.Builder("aa0ceb")
2 .firstName("Ernestina")
3 .lastName("Evans")
4 .email("ernestina@example.com")
5 .custom("groups",
6 LDValue.buildArray().add("Google").add("Microsoft").build())
7 .build()

The first argument to the builder is the user's key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Our Javadoc for LDUser.Builder shows you all the attributes that LaunchDarkly supports by default. In addition to these, you can pass us any of your own user data by passing custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation

Most of our built-in attributes, like names and e-mail addresses, expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans or numbers. If you enter a custom value that looks like a number or a boolean, it is interpreted that way. The Java SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Private user attributes in the Java SDK

You can optionally configure the Java SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Java SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • When creating the LDConfig object, you can call the allAttributesPrivate method, which takes in a boolean parameter. If true, all user attributes except the key for all users are removed before the SDK sends the user to LaunchDarkly.
  • When creating the LDConfig object, you can call the privateAttributes method, which takes in a set of custom or built-in attributes as a parameter. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.
1LDConfig configWithAllAttributesPrivate = new LDConfig.Builder()
2 .events(
3 Components.sendEvents()
4 .allAttributesPrivate(true)
5 )
6 .build();
7
8LDConfig configWithSpecificAttributesPrivate = new LDConfig.Builder()
9 .events(
10 Components.sendEvents()
11 .privateAttributes(UserAttribute.NAME, UserAttribute.EMAIL,
12 UserAttribute.forName("someCustomAttribute"))
13 )
14 .build();

You can also mark attributes as private when building the user object by calling the equivalent “private” user builder method. For example:

1LDUser user = new LDUser.Builder("aa0ceb")
2 .privateEmail("test@example.com")
3 .build();

When this user is sent back to LaunchDarkly, the email attribute is omitted.

Anonymous users in the Java SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUser user = new LDUser.Builder("aa0ceb")
2 .anonymous(true)
3 .build();

You still need to generate a unique key for anonymous users. Session IDs or UUIDs work best for this. Each unique user key registers a user in the system, so capture and reuse your anonymous user's key between requests.

Lua

Feature flag targeting and rollouts are determined by the user you pass to your variation calls.

1local user = ld.makeUser({
2 key = "aa0ceb",
3 firstName = "Ernestina",
4 lastName = "Evans",
5 email = "ernestina@example.com",
6 custom = {
7 groups = { "Google", "Microsoft" }
8 }
9})

Let's walk through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

In addition to built-in attributes, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

To learn more about configuration options, read the API docs.

Node.js

Feature flag targeting and rollouts are determined by the user you pass to your variation calls. In the Node.JS SDK, users are JSON objects. Here's an example:

1var user = {
2 "key": "aa0ceb",
3 "firstName": "Ernestina",
4 "lastName": "Evans",
5 "email": "ernestina@example.com",
6 "custom": {
7 "groups": ["Google", "Microsoft"]
8 }
9};

Let's walk through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Besides the key, LaunchDarkly supports the following attributes at the "top level". All of these are optional:

  • ip: Must be an IP address.
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user's e-mail address. If an avatar URL is not provided, LaunchDarkly uses Gravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name.
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to built-in attributes, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation
Built-in attributes, like names and email addresses, expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans, or numbers. If you enter a custom value on our dashboard that looks like a number or a boolean, it is interpreted that way.

Custom attributes let you target users according to any data that you send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to LaunchDarkly becomes available on your dashboard.

Private user attributes in the Node.js SDK

You can optionally configure the Node.js SDK to treat some or all user attributes as Private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Node.js SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • In the LaunchDarkly config, you can set allAttributesPrivate to true. If this is enabled, all user attributes except the key for all users are removed before the SDK sends the user to LaunchDarkly.
  • In the LaunchDarkly config object, you can define a list of privateAttributeNames. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.

You can also define a set of privateAttributeNames on the user object. For example:

1var user = {
2 "key": "aa0ceb",
3 "email": "test@example.com",
4 "privateAttributeNames": ["email"]
5};

When this user is sent back to LaunchDarkly, the email attribute is removed.

Anonymous users in the Node.js SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1var user = {"key":"aa0ceb", "anonymous": true};

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

PHP

Feature flag targeting and rollouts are determined by the user you pass to your Variation calls. In the PHP SDK, we use a builder pattern to construct users. Here's an example:

1$user = (new LDUserBuilder("aa0ceb"))->firstName("Ernestina")->lastName("Evans")->email("ernestina@example.com")->custom(["groups" => array("Google","Microsoft")])->build();

Let's walk through this snippet. The first argument to LDUserBuilder is the user's key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Besides the key, LaunchDarkly supports the following attributes at the "top level". All of these are optional:

  • ip: Must be an IP address.
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user's e-mail address. If an avatar URL is not provided, LaunchDarkly uses Gravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name.
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to these, you can pass us any of your own user data by passing custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation
Most of our built-in attributes (like names and e-mail addresses) expect string values. Custom attributes values can be strings, booleans (like true or false), numbers, or lists of strings, booleans or numbers. If you enter a custom value on our dashboard that looks like a number or a boolean, it'll be interpreted that way. The PHP SDK is strongly typed, so be aware of this distinction.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the PHP SDK

You can optionally configure the PHP SDK to treat some or all user attributes as private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the PHP SDK there are two ways to define private attributes for the entire LaunchDarkly client:

In the LaunchDarkly config, you can set allAttributesPrivate to true. If this is enabled, all user attributes (except the key) for all users are removed before the SDK sends the user to LaunchDarkly. In the LaunchDarkly config object, you can define a list of privateAttributeNames. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.

You can also mark attributes as private when building the user object by calling the equivalent "private" LDUserBuilder method. For example:

1$user = (new LDUserBuilder('aa0ceb'))
2 ->privateEmail('test@example.com')
3 ->build();

When this user is sent back to LaunchDarkly, the email attribute are removed.

Anonymous users in the PHP SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1$user = (new LDUserBuilder("aa0ceb"))->anonymous(true)->build();

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

Python

Feature flag targeting and rollouts are determined by the user you pass to your Variation calls. In the Python SDK, users are simply dictionaries. Here's an example:

1user = {
2 "key": "aa0ceb",
3 "firstName": "Ernestina",
4 "lastName": "Evans",
5 "email": "ernestina@example.com",
6 "custom": {
7 "groups": ["Google", "Microsoft"]
8 }
9}

Let's walk through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Besides the key, LaunchDarkly supports the following attributes at the "top level". All of these are optional:

  • ip: Must be an IP address.
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user's e-mail address. If an avatar URL is not provided, LaunchDarkly uses Gravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name.
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to built-in attributes, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

Custom attribute type interpretation
Built-in attributes, like names and email addresses, expect string values. Custom attributes values can be strings, booleans like true or false, numbers, or lists of strings, booleans, or numbers. If you enter a custom value on our dashboard that looks like a number or a boolean, it is interpreted that way.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the Python SDK

You can optionally configure the Python SDK to treat some or all user attributes as Private user attribute. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Python SDK there are two ways to define private attributes for the LaunchDarkly client:

  • In the LaunchDarkly config, you can set all_attributes_private to true. If this is enabled, all user attributes (except the key) for all users are removed before the SDK sends the user to LaunchDarkly.
  • In the LaunchDarkly config object, you can define a list of private_attribute_names. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.

You can also define a set of privateAttributeNames on the user object. For example:

1user = {
2 "key": "aa0ceb",
3 "email": "test@example.com",
4 "privateAttributeNames": ["email"]
5}

When this user is sent back to LaunchDarkly, the email attribute are removed.

Anonymous users in the Python SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1user = { "key":"aa0ceb", "anonymous": True }

You still need to generate a unique key for anonymous users. Session IDs or UUIDs work best for this. Anonymous users still count toward your plan's MAU limit, so make sure you capture and reuse your anonymous user's key between requests.

Ruby

Let's walk through this snippet. The most important attribute is the user key. In this case, we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes, like firstName, email, and the custom attributes, are optional. The attributes you specify appear on your LaunchDarkly dashboard automatically, so you can start making user segments and targeting users with these attributes right away.

Besides the key, LaunchDarkly supports the following attributes at the "top level". All of these are optional:

  • ip: Must be an IP address.
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user's e-mail address. If an avatar URL is not provided, LaunchDarkly uses Gravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name.
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to built-in attributes, you can pass any of your own user data using custom attributes, like the groups attribute in the example above.

A note on attribute keys

All user attribute keys (both built-in and custom attributes) must be symbols and not strings.

Custom attribute type interpretation

Most of our built-in attributes, like names and e-mail addresses, expect string values. Custom attribute values can be strings, booleans like true or false, numbers, or lists of strings, booleans or numbers. If you enter a custom value that looks like a number or a boolean, it is interpreted that way.

Custom attributes let you target users according to any data that you want to send to LaunchDarkly, including organizations, groups, and account plans. Anything you pass to us becomes available on your dashboard.

Private user attributes in the Ruby SDK

You can optionally configure the Ruby SDK to treat some or all user attributes as Private user attributes. Private user attributes can be used for targeting purposes, but are removed from the user data sent back to LaunchDarkly.

In the Ruby SDK there are two ways to define private attributes for the entire LaunchDarkly client:

  • In the LaunchDarkly config, you can set all_attributes_private to true. If this is enabled, all user attributes (except the key) for all users are removed before the SDK sends the user to LaunchDarkly.
  • In the LaunchDarkly config object, you can define a list of private_attribute_names. If any user has a custom or built-in attribute named in this list, it are removed before the SDK sends the user to LaunchDarkly.

You can also define a set of privateAttributeNames on the user object. For example:

1user = {
2 key: "aa0ceb",
3 firstName: "Ernestina",
4 lastName: "Evans",
5 email: "ernestina@example.com",
6 custom: {
7 groups: ["Google", "Microsoft"]
8 },
9 privateAttributeNames: ['email']
10}

When this user is sent back to LaunchDarkly, the email attribute are removed.

Anonymous users in the Ruby SDK

You can distinguish logged-in users from anonymous users in the SDK, as follows:

1user = { key: "aa0ceb", anonymous: true }

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