Custom attributes

Read time: 2 minutes

Last edited: Mar 17, 2023

Overview

This topic explains what custom attributes are and how to configure them.

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

Here is an example context which contains custom attributes:

"context": {
  "kind": "user",
  "name": "Anna",
  "key": "user-key-123abc",
  "email": "anna@globalhealthexample.com",
  "jobFunction": "doctor"
}

Custom attributes are environment-specific. They are not shared between environments or projects.

There is no limit to the number of custom attributes you can have. However, adding custom attributes does increase the size of the context object. JavaScript-based client-side SDKs send the context during initialization, so a large number of custom attributes may mean it takes longer for the SDK to initialize. To learn more, read Initialize the client.

Creating custom attributes

Custom and built-in attributes cannot share names

If you create a custom attribute with a name already in use by a built-in attribute, the SDK will behave unpredictably during feature flag evaluation. For a list of built-in attributes and their names, read Built-in attributes.

You can create custom attributes in two ways:

By configuring them within your SDK, or
By adding them from a flag's Targeting tab.

Configuring attributes within your SDK

When you configure attributes in your SDK, they will appear as an option in targeting rules after the SDK has passed those attributes to LaunchDarkly. To learn how to configure attributes within your SDK, read User and context configuration.

Attributes that you have configured in your SDK may not appear in the Contexts list or in a flag's targeting rules yet for the following reasons:

The SDK has not yet passed events containing the attribute to your current environment in LaunchDarkly.
The SDK sent the events very recently and LaunchDarkly has not processed them yet.
Ad blockers or proxies are preventing the events from reaching LaunchDarkly. If so, the SDK will still evaluate contexts correctly.
Your SDK is not configured to send events to LaunchDarkly. To learn more, read Configuration.
You have exceeded your client-side context instance limit for the month. To learn more, read Understanding client-side MCI limits.

Projects and environments do not share custom attributes or values because the SDK key, mobile key, or client-side ID you configured the SDK with is environment-specific. To learn more about configuring these, read the "Getting started" section for your SDK.

Adding attributes from a flag's Targeting tab

To add custom attributes from a flag's Targeting tab, manually enter the name of the attribute in the "Select an attribute" field within a targeting rule:

Creating a custom "Location" user context attribute from a flag's "Targeting" tab.

To learn more, read Targeting rules.

If you add a custom attribute from a flag's Targeting tab, flag evaluations won't be able to use the attribute until you also configure it within your SDK.

Setting custom attribute values

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

boolean
number
string
array
JSON object

Null JSON values

null is a valid JSON type, but it is not a valid attribute value in LaunchDarkly. In LaunchDarkly, null is equivalent to the attribute being undefined. For example, in a JSON representation of a context, "name": null is equivalent to omitting the name attribute value completely. This applies to both built-in attributes and custom attributes.