An introduction to contexts

Overview

This guide summarizes what contexts are and provides resources to learn how to use them.

Contexts are the upgraded version of LaunchDarkly's existing "user" data objects. Previously, flags could only target users, which was limiting if you wanted to target organizations, devices, groups, or other entities. Contexts give you much more targeting flexibility. They let you create targeting rules for feature flags based on a variety of different information, including attributes pertaining to users, organizations, devices, and more. To learn more, read Contexts.

In this guide you can learn more about:

• Context kinds
• Multi-contexts
• Context instances and versions
• Context attributes, including built-in attributes and custom attributes
• Segments
• Using the Contexts list
• Upgrading your SDKs to use contexts

Context kinds

Each context has a context kind, which describes the type of attributes it contains.

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.

To learn more, read Context kinds.

Here are example contexts that have the "user," "organization," and "device" context kinds:

// a user context
"context": {
  "key": "user-key-123abc",
  "kind": "user",
  "name": "Sandy",
  "email": "sandy@example.com",
  "gymMember": "true"
  }
// an organization context
"context": {
  "key": "organization-key-123abc",
  "kind": "organization",
  "name": "Global Health Gym",
  "address": {
    "street": "123 Main Street",
    "city": "Springfield"
    }
  }
// a device context
"context": {
  "key": "device-key-123abc",
  "kind": "device",
  "type": "iPad",
  "operating_system": "iPadOS 15",
  "deviceId": 12345
  }
COPY

You can create new context kinds in the LaunchDarkly user interface (UI), or automatically when you evaluate a context using a LaunchDarkly SDK. To learn more, read Creating context kinds.

Multi-contexts

When you evaluate a feature flag within your application, the flag's targeting rules can use information from more than one kind of context at the same time. Contexts that include multiple context kinds are called "multi-contexts."

Here's an example of the "user," "organization," and "device" context kinds from the previous section combined into one multi-context:

"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-123abc",
    "name": "Sandy",
    "email": "sandy@example.com",
    "gymMember": "true"
    },
  "organization": {
    "key": "organization-key-123abc",
    "name": "Global Health Gym",
    "address": {
      "street": "123 Main Street",
      "city": "Springfield"
      }
    },
  "device": {
    "key": "device-key-123abc",
    "type": "iPad",
    "operating_system": "iPadOS 15",
    "deviceId": 12345
    }
}
COPY

This configuration allows you to target the user, organization, and device all together to ensure you serve the correct variation. This helps eliminate risk and ensure accuracy in complex deliveries.

To learn more, read Multi-contexts and context instances.

Context instances and versions

Any particular individual context, independent of all other relationships, is a context instance. Each context instance has a unique combination of associated contexts. For example, suppose your gym fitness app uses both organization and user contexts. This means you can target features based on the location and affiliation of each gym, and separately target features based on individual end users.

If end user Sandy logs into your fitness app from two different gyms they visit, that is two different context instances.

These two context instances would have the following associated user, device, and organization contexts:

• user: Sandy, device: iPhone, organization: Springfield North
• user: Sandy, device: iPhone, organization: Springfield East

A context instance version is a context instance that's recorded from a unique source application or LaunchDarkly SDK. For example, if your application uses both the iOS SDK and the Go SDK, then you may see both an iOS SDK context instance version from when Sandy visited your app at the gym on their iPhone, and a Go SDK context instance version from when Sandy visited from the gym's check-in kiosk.

These two context instance versions would have the following associated user and device contexts:

• user: Sandy, device: iPhone, location: Springfield North, iOS SDK instance
• user: Sandy, device: ThinkPad, location: Springfield North, Go SDK instance

This illustration shows example contexts, context instances, and context instance versions:

To learn more, read Context instances.

Context attributes

Context attributes include all of the information about a context that LaunchDarkly can use in a feature flag evaluation. You can use context attributes in targeting rules for flags and rule-based segments. For example, imagine you want a flag to serve the true variation to user contexts that are within the United States, or false to device contexts that use iOS. You can use context attributes to accomplish this. To learn more, read Context attributes.

Built-in attributes

LaunchDarkly has the following built-in attributes for contexts: kind, key, name, and anonymous. While LaunchDarkly provides built-in attribute fields for you to fill in, the SDK does not automatically collect any information. If you want to target your users based on any built-in attributes, you must supply their values.

To learn more, read Built-in attributes.

Custom attributes

In addition to built-in attributes, you can create your own custom attributes according to your needs. To learn more, read Custom attributes.

Here is an example of a user context with the built-in attributes of key, kind, and name, and the custom attributes of country and beta-tester:

"context": {
  "key": "user-key-123abc",
  "kind": "user",
  "name": "Jesse",
  "country": "Canada",
  "beta-tester": "true"
  }
COPY

Segments

Segments let you target groups of contexts individually or by attribute. Segments are useful for keeping groups of contexts, like beta-users or enterprise-customers, up to date. They allow you to more quickly turn features on or off for certain groups with confidence.

There are several ways to define which contexts belong to a particular segment. You can define a segment by:

• using targeting rules, for example, all contexts with an email attribute that ends in ".edu".
• using a list of context keys that you upload to LaunchDarkly in a .csv file, for example, if you are collecting the emails of customers who want to participate in beta testing in a spreadsheet.
• syncing a list of context keys from a third-party application, for example, if you already keep a list of customers in another application.

To learn more, read Segments.

Using the Contexts list

The Contexts list shows you all of the contexts that have encountered feature flags in your application. You can select any context to view its context details page. To learn more, read The Contexts list.

Here is an image of the Contexts list:

The context details page gives you a summary view of how the context experiences all of the features in your app, and lets you customize their experience from one screen. To learn more, read The context details page.

Here is an examples of the context details page:

Upgrading your SDKs to use contexts

You can only use contexts if your SDKs support them. If you are a new customer, use the latest version of the SDKs and make sure they support contexts. If you are an existing customer, you must upgrade your SDKs to the latest versions. For a list of SDKs that support contexts and links to their migration guides, read SDKs.

If you use the Relay Proxy, you also need to update it to version 7.0 or later before you upgrade your SDKs. To learn more about upgrading, read the Relay Proxy 7.0.0 release notes. To upgrade to the latest Relay Proxy version, visit Relay Proxy releases on GitHub.

Conclusion

With contexts, you can now use flag targeting on a wide range of entities beyond just users. This guide provided a high-level introduction to the concept of contexts and how to use them. For a full tutorial on how to upgrade from users to contexts, read Best practices for upgrading users to contexts.