No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

Context kinds

Read time: 7 minutes
Last edited: May 30, 2024

Overview

This topic explains what context kinds are and how to manage them.

About context kinds

Contexts are people, services, machines, or other resources that encounter feature flags in your product.

Each context has one or more context kinds that you can use to categorize context instances for targeting and Experimentation. For example, you may know:

  • the username, first name, last name, and email address of a person. You might include these context attributes in contexts with a "user" context kind.
  • the company, department, and location of an organization. You might include these context attributes in contexts with an "organization" context kind.
  • the device, model, and operating system of an environment. You might include these attributes in contexts with a "device" context kind.

When you create a context kind, you provide a name, key, and description. Then, any attributes that you add to a context of that kind become part of the context kind. You do not need to define the attributes themselves when you create the context kind.

Here is an example of a context with a kind of "organization":

"context": {
"kind": "organization",
"key": "org-key-123abc",
"name": "Global Health Gym",
"address": {
"street": "123 Main Street",
"city": "Springfield"
}
}

Context kinds let you group context attributes together conceptually. When you create individual targets or add targeting rules for a flag or a segment, the available context attributes are organized by context kind. Contexts can have multiple context kinds, called a multi-context. To learn more, read Multi-contexts and context instances.

Context kinds are specific to LaunchDarkly projects. After you create them in a project, they are available in any of the environments within that project.

Built-in context kinds

The only built-in default context kind is user. This is the context kind targeting rules use by default and, if you use Experimentation, the default randomization unit for experiments.

Automatic environment attributes enable additional built-in context kinds

If you enable automatic environment attributes in a mobile SDK, the built-in context kinds ld_device and ld_application also become available after your SDK begins sending this information to LaunchDarkly. To learn how to enable automatic environment attributes, read Automatic environment attributes.

View context kinds

You can view a list of context kinds that have been identified or evaluated within the last 30 days by navigating to the Contexts list and clicking Kinds.

The context kinds list includes all of the built-in and manually created context kinds within your project:

The context kinds list.
The context kinds list.

The context kinds list includes the following columns:

  • In use: indicates whether an SDK has ever sent a context with this kind to LaunchDarkly
  • Archived: indicates whether you can use this context kind in flag and segment targeting rules.
    • Archived context kinds are automatically hidden from the list. Check the Show archived context kinds checkbox to show them:
The context kinds list with the "Show archived context kinds" checkbox called out.
The context kinds list with the "Show archived context kinds" checkbox called out.
  • Available for experiments: indicates whether you can use this context kind as a randomization unit in experiments. To learn more, read Randomization units.

You can filter contexts based on their context kind from the Contexts list. To learn more, read The Contexts list.

Contexts appear individually in the Contexts list

Your application may evaluate a feature flag for a multi-context, that is, one that contains multiple context kinds. For example, your application may send a single multi-context that contains the "user," "organization," and "device" context kinds, all in one evaluation call in the LaunchDarkly SDK. When you do this, all three individual contexts appear separately in your Contexts list. You can use the context kind filters to search for them separately.

You can view the context kind for a particular context on the context details page, in the "Attributes" section. You can view the context kind for a context instance on the instance details page, in the "Attributes" section. To learn more, read The context details page.

You can also use the REST API: Get context kinds

Create context kinds

Creating context kinds is an Admin-only feature

You can only create new context kinds if you're a LaunchDarkly Admin or Owner, or have a custom role that allows the createContextKind action. To learn more, read About member roles and Context kind actions.

You can create context kinds in the LaunchDarkly user interface (UI), or automatically when you evaluate a context using a LaunchDarkly SDK.

To create a context kind in the LaunchDarkly UI:

  1. Navigate to the Contexts list.
  2. Click Kinds.
  3. Click Create kind.
  4. The "New context kind" dialog appears.
  5. Enter a Name for the context kind. This appears in the context kind list, and as a filter option in the Contexts list.
  6. Enter a Key for the context kind. You cannot change this later. It appears in the Contexts list and on the context details page in the "Attributes" section.
  7. (Optional) Enter a Description for the context kind.
  8. (Optional) Check the Available for experiments checkbox if you want to be able to use this context kind as a randomization unit in experiments. To learn more, read Randomization units.
  • Select an industry-standard randomization unit to map the context kind to.
  • (Optional) Check the "Set as the default for experiments" checkbox if you want new experiments to default to this context kind as the randomization unit.
Context kinds available for experiments must use valid randomization units

Using invalid randomization units will result in invalid experiment results. To learn more, read Randomization units. If you're unsure of which randomization unit to use, contact Support for help determining valid context kind selections.

  1. Click Create kind.

To create a context kind automatically, create a context object in your LaunchDarkly SDK. When you evaluate a flag for the context, LaunchDarkly automatically creates a new context kind for that context's kind, if one of the same name does not already exist.

Try it in your SDK: Evaluating flags

You can also use the REST API: Create or update context kind

Edit context kinds

You can edit existing context kinds from the Contexts kinds list by clicking on the pencil edit icon next to the contest kind you want to edit.

You can edit the name and description of the context kind, but you cannot edit the key.

If you use Experimentation, you can also edit whether the context kind is available for experiments, the standard randomization unit the context kind maps to, and whether the context kind should be the default for experiments. To learn more, read Randomization units.

Archive context kinds

Archiving a context kind makes it unavailable for flag and segment targeting and unavailable for use in experiments.

To archive a context kind:

  1. Navigate to the Contexts list.
  2. Click Kinds.
  3. Click the pencil edit icon next to the context kind you want to archive. The "Edit context kind" dialog appears.
  4. Click Archive.

The context kind is now hidden from the contexts kinds list and is not available in flag and segment targeting rules.

Restoring archived context kinds

To restore an archived context kind:

  1. Navigate to the Contexts list.
  2. Click Kinds.
  3. Check the Show archived context kinds checkbox at the top of the context kinds list.
  4. Click the pencil edit icon next to the context kind you want to restore. The "Edit context kind" dialog appears.
  5. Click Restore.

The context kind displays on the context kinds list and is available for targeting.

You can also use the REST API: Create or update context kind