• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""


    Contexts and segments

    Read time: 5 minutes
    Last edited: Feb 01, 2023
    Welcome to the custom contexts Early Access Program

    Welcome to the custom contexts Early Access Program (EAP)!

    To learn more about contexts, read An introduction to contexts.

    To learn more about what's included in the contexts EAP, read What's included in the contexts EAP?


    This category has documentation topics about LaunchDarkly contexts and segments. Contexts are people, services, machines, or other resources that encounter feature flags in your product. Segments let you target groups of contexts individually or by attribute.

    What's included in the contexts EAP?

    We have upgraded the majority of LaunchDarkly's core functionality to support custom contexts, as well as many of our most popular SDKs. Not all LaunchDarkly features support contexts yet.

    Development work on upgrading to contexts is ongoing. We will update this list when upgraded features are available, as well as the Changelog.

    The following areas of LaunchDarkly do not yet support contexts:

    • Third-party integrations
    • LaunchDarkly's instance for federal customers

    The following areas of LaunchDarkly have limited support for contexts:

    • Big Segments only support contexts with a kind of "user." To learn more, read Big Segments.
    • Experimentation has limited functionality. You can run experiments on different context kinds, but you cannot assign experiment variations based on them. To learn more, read Experimentation.
    • The Segment and mParticle Data Export destinations have limited functionality. You cannot specify context kinds for either destination.
    • Some LaunchDarkly SDKs do not yet support contexts. Instead, they rely on legacy user objects. To learn which SDKs are available to use with contexts, read SDKs.

    Understanding the foundations of contexts

    Contexts are an evolution of a previously-existing concept, "users." Over time, we found that many LaunchDarkly customers have businesses that aren't focused on users. Instead, these customers care about accounts, devices, locations, or other custom contexts unique to their business.

    Contexts let you create targeting rules for feature flags based on a variety of different information, including attributes pertaining to users, organizations, devices, and more. You can be as specific as targeting a flag to a single end user, or as broad as targeting your entire customer base.

    When a flag evaluation occurs, the feature flag uses the context to understand what variation to serve. You can manage the way contexts interact with flags, and which contexts encounter which flags, by targeting flags to specific contexts. You can even choose which contexts to include or exclude in the data you collect.

    For a list of SDKs that support contexts, read our SDK documentation.

    To learn more about upgrading to contexts, read Best practices for upgrading users to contexts.

    Example: Anna at Global Health

    As an example, let's assume Anna is one of your end users. She is a doctor who works for a hospital chain called Global Health Services. Anna has two mobile devices, an Android phone and an iPad tablet. Anna uses your application on both devices as part of her work.

    Given this information, you may know the following things about Anna:

    • her name, email, and job function ("doctor"),
    • her organization's name ("Global Health Services") and address,
    • her device's type, operating system, and device ID, for each mobile device.

    You may want to target several different contexts that would impact Anna’s experience. Using contexts, you can include the following in your application:

    • You can target Anna in a feature flag based on her job function, as part of a feature that allows all doctors to access patient records.
    • You can target her devices with a feature flag, as part of a feature that provides different styling for Android and iPad devices.
    • You can run an experiment to test out a new feature, and ensure that Anna and everyone in her company receives the same variation, by targeting your experiment to her organization.

    Understanding contexts and context kinds

    Contexts describe individual people, users, devices, and more.

    You can designate different conceptual groupings of this information into context kinds. Each context has a required attribute called kind that describes the type of attributes it contains. Kinds expand on LaunchDarkly's built-in and custom attributes, allowing you to create targetable objects that meet your needs precisely. You can define context kinds from the Contexts list, under the Kinds tab. To learn more, read Context kinds.

    Context attributes can be strings, booleans, numbers, arrays, or JSON objects. When you evaluate a feature flag within your application, the flag's targeting rules use information from one or more kinds of contexts. When you build your targeting rules, the attributes are automatically organized by context kind. To learn more, read Targeting with flags.

    When you use the LaunchDarkly SDK to evaluate a flag, you provide a context to that call. To learn more, read User and context configuration.

    After different contexts encounter your application, you can view them on the Contexts list. To learn more, read The Contexts list.

    Example: Contexts that affect Anna's experience

    Using the example above, we can describe the information about Anna using three different context kinds:

    • her name, email, and job function ("doctor") are part of a "user" context,
    • her organization's name ("Global Health Services") and address are part of an "organization" context,
    • her device's type, operating system, and device ID are part of a "device" context.

    Here's an example of what each context looks like:

    // a user context
    "context": {
    "kind": "user",
    "name": "Anna",
    "email": "anna@globalhealthexample.com",
    "jobFunction": "doctor"
    // an organization context
    "context": {
    "kind": "organization",
    "name": "Global Health Services",
    "address": {
    "street": "123 Main Street",
    "city": "Springfield"
    // a device context
    "context": {
    "kind": "device",
    "type": "iPad",
    "operating_system": "iPadOS 15",
    "deviceId": 12345


    Sometimes you want to have your feature flags target based on data from multiple contexts. For example, maybe you want to serve one variation to doctors like Anna who work at the Global Health Services Springfield location. But you want to serve a different variation to nurses at the Springfield location, and you want to serve a third variation to doctors at the Midway location. In this situation, you can have the LaunchDarkly SDK send multiple contexts at once during the flag evaluation, so that LaunchDarkly can evaluate targeting rules using data from both the "user" and "organization" contexts at the same time. When you evaluate a set of multiple contexts at once, this is called a multi-context. The context kind is set to multi.

    Here's an example:

    // this example multi-context contains two associated contexts,
    // one for user and one for organization
    "context": {
    "kind": "multi",
    "user": {
    "name": "Anna",
    "email": "anna@globalhealthexample.com",
    "jobFunction": "doctor"
    "organization": {
    "name": "Global Health Services",
    "address": {
    "street": "123 Main Street",
    "city": "Springfield"

    Understanding context instances

    We refer to any particular individual context, independent of all other relationships, as a context instance. Each context instance has a unique combination of associated contexts. For example, suppose a hospital's employee app uses organization, device, and user contexts. This means you can target features based on the location and affiliation of each hospital, separately target features based on individual end users, and separately target features based on the device employees use to log in.

    When Anna from Global Health Services logs into your application from her Android in Springfield, that's recorded as a context instance. When Anna logs into your app from her iPad in Midway, that's recorded as another context instance.

    The context instances would then be the combination of the associated contexts:

    • Anna, Springfield, Android device
    • Anna, Midway, iPad

    The multiple contexts that appear in this context instance are called associated contexts. For example, we might say that Anna is one of several users associated with the organization: Global Health Services context.

    Depending on how your application is set up, LaunchDarkly records one or more context instance versions each time Anna logs in. 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 Android SDK and the Go SDK, then you'll see two different context instance versions, one from Anna from Global Health Services on an Android from the Android SDK, and another from Anna from the Go SDK.

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

    An example of associated contexts, context instances, and context instance versions.
    An example of associated contexts, context instances, and context instance versions.

    You can view context instances, context instance versions, and expected flag variations on the Context details page.

    Here is what Anna's Context details page would look like:

    An image of the context details page.
    An image of the context details page.

    To learn more, read The context details page.

    Here are the topics in this category:

    • The Contexts list
    • Context attributes
    • Context kinds
    • Segments
    • Anonymous contexts