Multi-contexts and context instances

Overview

This topic includes information about multi-contexts and context instances. Contexts are people, services, machines, or other resources that encounter feature flags in your product. Multi-contexts are combinations of several context kinds into one context. Any unique combination of one or more contexts that have encountered a feature flag is a context instance.

Multi-contexts

Sometimes you want your feature flags to target entities based on data from multiple contexts.

For example, imagine Anna is a doctor who works for a hospital chain called Global Health Services. Anna works at two different locations, Springfield and Midway. Jesse is a nurse that works with Anna at the Springfield location.

Maybe you want to serve one variation of a flag to doctors working at the Global Health Services Springfield location, and 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 within one evaluation context, this is called a multi-context. The context kind is set to multi.

These example multi-contexts contain two associated contexts, one for user and one for organization:

// Anna's multi-context
"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-123abc",
    "name": "Anna",
    "email": "anna@globalhealthexample.com",
    "jobFunction": "doctor"
    },
  "organization": {
    "key": "org-key-123abc",
    "name": "Global Health Services",
    "address": {
      "street": "123 Main Street",
      "city": "Springfield"
      }
    }
  }
// Jesse's multi-context
"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-456def",
    "name": "Jesse",
    "email": "jesse@globalhealthexample.com",
    "jobFunction": "nurse"
    },
  "organization": {
    "key": "org-key-123abc",
    "name": "Global Health Services",
    "address": {
      "street": "123 Main Street",
      "city": "Springfield"
      }
    }
  }
COPY

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

The multiple contexts that appear in a multi-context are called associated contexts. For example, we might say that the Anna user context and the Global Health Services organization context are associated contexts.

Context instances

We refer to any unique combination of one or more contexts that have encountered a feature flag as a context instance.

For example, suppose a hospital's employee app uses organization, device, and user contexts. When Anna from Global Health Services logs into your application from her Android in Springfield, that's recorded as one instance. When Anna logs into your app from her iPad in Midway, that's recorded as second instance. Even though Anna's user context appears in both, LaunchDarkly considers these two different context instances because they contain different combinations of context keys.

The two context instances are the combination of their associated contexts:

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

Here is what these two context instances would look like:

// The first context instance
"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-123abc",
    "name": "Anna",
    "email": "anna@globalhealthexample.com",
    "jobFunction": "doctor"
    },
  "organization": {
    "key": "org-key-123abc",
    "name": "Springfield Global Health Services",
    "address": {
      "street": "123 Main Street",
      "city": "Springfield"
      }
    },
  "device": {
    "key": "device-key-123abc",
    "name": "Pixel 7",
    "os": "Android 13"
    }
  }
// The second context instance
"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-123abc",
    "name": "Anna",
    "email": "anna@globalhealthexample.com",
    "jobFunction": "doctor"
    },
  "organization": {
    "key": "org-key-456def",
    "name": "Midway Global Health Services",
    "address": {
      "street": "456 1st Ave",
      "city": "Midway"
      }
    },
  "device": {
    "key": "device-key-456def",
    "name": "iPad",
    "os": "iOS"
    }
  }
COPY

For billing purposes, customers who are billed by contexts may be billed for one context, if their primary context kind is user, or for two contexts, if their primary context kind is organization or device. Customers who are billed by monthly active users (MAU) would be billed for one context, because there is only one unique user context. To learn more, read Account usage metrics.

A context appearing alone, without any other associated contexts, is also considered a context instance. For example, this stand-alone context and this multi-context also represent two context instances:

// The first context instance
"context": {
  "kind": "user",
  "key": "user-key-123abc",
  "name": "Anna",
  "email": "anna@globalhealthexample.com",
  "jobFunction": "doctor"
  }
// The second context instance
"context": {
  "kind": "multi",
  "user": {
    "key": "user-key-123abc",
    "name": "Anna",
    "email": "anna@globalhealthexample.com",
    "jobFunction": "doctor"
    },
  "organization": {
    "key": "org-key-456def",
    "name": "Midway Global Health Services",
    "address": {
      "street": "456 1st Ave",
      "city": "Midway"
      }
    },
  "device": {
    "key": "device-key-456def",
    "name": "iPad",
    "os": "iOS"
    }
  }
COPY

Like the previous example, customers being billed by context would be billed for one context, and customers being billed by monthly active users (MAU) would be billed for one MAU.

Two different SDKs might encounter the same context, as defined by their unique combination of kind and key, with different context attributes. Because they have the same unique combination of kind and key, the contexts are not considered separate contexts or separate context instances. Instead, they are two different versions of the same context instance.

Context instance versions

A context instance version is a context instance that's recorded from a unique source application or LaunchDarkly SDK. Depending on how your application is set up, LaunchDarkly may record one or more context instance versions each time Anna logs in. For example, if your application uses both the Android SDK and the Go SDK in different places, and Anna logs in from both places, then you'll see two different context instance versions: one from Anna from the Android SDK, and another from Anna from the Go SDK.

This illustration shows example 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:

To learn more, read The context details page.