Custom attributes

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 are example contexts containing custom attributes:

// A single context
"context": {
  "kind": "user",
  "name": "Anna",
  "key": "user-key-123abc",
  "email": "anna@globalhealthexample.com",
  "jobFunction": "doctor"
}
// A multi-context
"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-456def",
    "name": "Jesse",
    "city": "Springfield"
    },
  "organization": {
    "key": "organization-key-123abc",
    "name": "Acme, Inc",
    "city": "Midway"
    }
  }
COPY

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

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.

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.

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 "Attribute" field within a targeting rule:

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.