Context configuration
Read time: 46 minutes
Last edited: Nov 20, 2024
Overview
This topic explains how to configure contexts in LaunchDarkly SDKs. This feature is available for all SDKs.
A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users." To learn more, read Contexts.
Configuration for contexts
Every LaunchDarkly SDK lets you configure contexts to return specific data to LaunchDarkly. Any attributes you pass to LaunchDarkly as part of a context become available on the Contexts list. The attribute values determine which variation of a feature flag, or which version and prompt from an AI config, the customer receives.
Here is an image of the Contexts list:
Every context is required to have a key
. Keys are always transmitted to LaunchDarkly. Typically, you supply the key when you create the context. For some client-side SDKs, if you mark the context as anonymous then SDK can generate the key for you. To learn more, read Anonymous contexts and users.
Keys must be a string type. Keys must be unique, deterministic, and should not contain personally identifiable information (PII). Keys must be consistent, which means the same person must correspond to the same key across different services to contribute to consistent flag evaluations. You can use a primary key or a hash, as long as the same person always has the same key. We recommend using a hash if possible.
The SDK only evaluates flags or customizes AI configs based on the context you define and then provide in the call. The SDK does not use the attributes shown on the Contexts list, and context attributes are not synchronized across SDK instances. You must provide all applicable attributes for each evaluation in the SDK for your targeting rules to apply correctly.
About built-in and custom attributes
Attributes other than the key are optional. There are two types of attributes: built-in attributes, which are LaunchDarkly names, and custom attributes, which you can name anything you choose.
The only built-in attributes for contexts are key
, kind
, name
, and anonymous
.
Only the key
is required. It must be a string.
The value of kind
can be:
- the key of an existing context kind that is already defined
- the key for a new context kind, which will be automatically created when this context is evaluated or identified
- the string
multi
, if this is a multi-context - omitted, in which case, it defaults to
user
The value of name
can be any string.
The value of anonymous
can be true
or false
. If not specified, it defaults to false
.
You can define additional attributes for a context by passing in a name and value for each. These additional attributes let you add targeting rules for your flags based on any data that you want to send to LaunchDarkly. Attribute values can be any JSON type, including boolean, number, string, array, or object. To learn more, read Context attributes.
If you create an attribute with a name already in use by a built-in attribute, the SDK will behave unpredictably.
The only built-in attributes for contexts are kind
, key
, name
, and anonymous
. If you work with an older SDK that only supports users, there are several additional built-in attributes.
To learn how to configure private attributes in your SDK, read Private attributes.
Details about each SDK's configuration are available in the SDK-specific sections below.
Client-side SDKs
Here are the configuration options for contexts in client-side SDKs:
- .NET (client-side)
- Android
- C++ (client-side)
- Electron
- Flutter
- iOS
- JavaScript
- Node.js (client-side)
- React Native
- React Web: The React Web SDK relies on the JavaScript SDK for context-related functionality.
- Roku
.NET (client-side)
Expand .NET (client-side) code sample
In the client-side .NET SDK, you can construct a Context
that only has a key by calling Context.New
. The context kind defaults to "user," or you can supply a different context kind. Alternatively, you can use Context.Builder
, which allows setting all properties.
The argument to Builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
Context context = Context.Builder("context-key-123abc").Set("firstName", "Sandy").Set("lastName", "Smith").Set("email", "sandy@example.com").Set("group", "microsoft").Build();
Here's how to construct a context with a context kind of something other than "user":
var context = Context.New(ContextKind.Of("organization"), "org-key-123abc");
Here's how to construct a multi-context, which includes multiple context kinds:
var userContext = Context.New("user-key-123abc");var orgContext = Context.New(ContextKind.Of("organization"), "org-key-123abc");var multiContext = Context.NewMulti(userContext, orgContext);
The optional name and kind attributes, which you can set with .Name()
and .Kind()
, expect string values. If the kind attribute is not specified, it is assumed to be "user." Other attribute values can be any JSON type, including booleans, numbers, strings, arrays, or objects. The SDK uses the LdValue
type to represent arrays and objects. The client-side .NET SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the .NET (client-side) SDK, read Private attributes.
To learn how to configure anonymous contexts in the .NET (client-side) SDK, read Anonymous contexts and users.
Android
Expand Android code sample
In the Android SDK, use a builder pattern to construct contexts. The argument to builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
LDContext context = LDContext.builder("context-key-123abc").set("email", "sandy@example.com").set("firstName", "Sandy").set("lastName", "Smith").set("group", "Microsoft").build();
Here's how to construct a context with a context kind of something other than "user":
LDContext context1 = LDContext.create(ContextKind.of("organization"), "org-key-123abc");
Here's how to construct a multi-context, which includes multiple context kinds:
LDContext multiContext = LDContext.createMulti(LDContext.create("user-key-123abc"),LDContext.create(ContextKind.of("device"), "device-key-123abc"));
The optional name and kind attributes, which you can set with .name()
and .kind()
, expect string values. If the kind attribute is not specified, it is assumed to be "user." Other attribute values can be any JSON type, including boolean, number, string, array, or object. The Android SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Android SDK, read Private attributes.
To learn how to configure anonymous contexts in the Android SDK, read Anonymous contexts and users.
LDUser
removalVersion 4 of the Android SDK replaced users with contexts. Starting in version 5, the deprecated LDUser
is removed. To learn more about replacing users with contexts, read the Android SDK 3.x to 4.0 migration guide and Best practices for upgrading users to contexts.
C++ (client-side)
Expand C++ (client-side) code sample
In the C++ (client-side) SDK, you can construct a context using the ContextBuilder
. The arguments to .Kind()
are the context kind and key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key, an email address, or a hash for the key, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
auto context = ContextBuilder().Kind("user", "user-key-123abc").Set("firstName", "Sandy").Set("lastName", "Smith").Set("groups", {"Google", "Microsoft"}).Build();
Here's how to construct a context with a context kind of something other than "user":
auto context = ContextBuilder().Kind("organization", "org-key-123abc").Build();
Here's how to construct a multi-context, which includes multiple context kinds:
auto context = ContextBuilder().Kind("user", "user-key-123abc").Name("Sandy").Kind("organization", "org-key-123abc").Name("Global Health Services").Build();
The name and kind attributes, which you can set with .Name()
and .Kind()
, expect string values. Other attribute values can be any JSON type, including boolean, number, string, array, or object.
To learn how to configure private attributes in the C++ (client-side) SDK, read Private attributes.
To learn how to configure anonymous contexts in the C++ (client-side) SDK, read Anonymous contexts and users.
Electron
Expand Electron code sample
The Electron SDK does not support contexts. Instead, it supports users. You can think of these as contexts with a context kind of "user." Other context kinds are not supported.
Here's an example of a user:
const user = {key: 'user-key-123abc',firstName: 'Sandy',lastName: 'Smith',email: 'sandy@example.com',custom: {groups: ['Google', 'Microsoft']}};
The key
property is the user's key. The key should uniquely identify each user. You can use a primary key or a hash, as long as the same user always has the same key. We recommend using a hash if possible. In this example, the hash is "user-key-123abc"
.
By default, when the SDK requests feature flags from LaunchDarkly, it makes an HTTP GET request with the user properties encoded in the URL. If you do not want user keys or other properties to be in request URLs, enable the useReport
option in your client configuration. The SDK sends user data in the body of an HTTP REPORT request instead.
Most of the built-in attributes, like names and email addresses, expect string values. Custom attribute values can be booleans, numbers, strings, or arrays. If you enter a custom value on the Users list that looks like a number or a boolean, the SDK interprets it that way.
To learn how to configure private attributes in the Electron SDK, read Private attributes.
To learn how to configure anonymous users in the Electron SDK, read Anonymous contexts and users.
Flutter
Expand Flutter code sample
In the Flutter SDK, use a builder pattern to construct contexts. The arguments to LDContextBuilder
are the context's kind and key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
final context = LDContextBuilder().kind('user', 'user-key-123abc').setString('email', 'sandy@example.com').setString('firstName', 'Sandy').setString('lastName', 'Smith').setString('group', 'microsoft').build();
Here's how to construct a context with a context kind of something other than "user":
final context = LDContextBuilder().kind('device', 'device-key-123abc').build();
Here's how to construct a multi-context, which includes multiple context kinds:
LDContextBuilder builder = LDContextBuilder();builder.kind('user', 'user-key-123abc').name('Sandy');builder.kind('organization', 'org-key-123abc').name('Global Health Services');LDContext context = builder.build();
The required kind
and optional name
attributes expect string values. Other attribute values can be any JSON type, including boolean, number, string, array, or object. Attribute values in the Flutter SDK use the LDValue
class to support the various underlying types for the values. The Flutter SDK is strongly-typed, so be aware of this distinction.
Starting in version 4, the Flutter SDK provides setters so that you do not have to create an LDValue
yourself. Instead, you can use setBool
, setNum
, and setString
when adding attributes to a context.
To learn how to configure private attributes in the Flutter SDK, read Private attributes.
To learn how to configure anonymous contexts in the Flutter SDK, read Anonymous contexts and users.
iOS
Expand iOS code sample
In the iOS SDK, you can construct a context using LDContextBuilder
. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
var contextBuilder = LDContextBuilder(key: "user-key-123abc")contextBuilder.trySetValue("name", .string("Sandy"))contextBuilder.trySetValue("email", .string("sandy@example.com"))let context = try? contextBuilder.build().get()
Here's how to construct a context with a context kind of something other than "user":
var contextBuilder = LDContextBuilder(key: "org-key-123abc")contextBuilder.kind("organization")let context = try? contextBuilder.build().get()
Here's how to construct a multi-context, which includes multiple context kinds:
var userBuilder = LDContextBuilder(key: "user-key-123abc")var deviceBuilder = LDContextBuilder(key: "device-key-123abc")deviceBuilder.kind("device")var multiBuilder = LDMultiContextBuilder()multiBuilder.addContext(try userBuilder.build().get())multiBuilder.addContext(try deviceBuilder.build().get())let context = try multiBuilder.build().get()
You can define additional attributes for a context by passing in a name and value for each. Additional attributes can be any JSON type, including boolean, number, string, array, or object.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn more about the specific context properties that are available in this SDK, read LDContextBuilder
.
To learn how to configure private attributes in the iOS SDK, read Private attributes.
To learn how to configure anonymous contexts in the iOS SDK, read Anonymous contexts and users.
LDUser
removalVersion 8 of the iOS SDK replaced users with contexts. Starting in version 9, the deprecated LDUser
is removed. To learn more about replacing users with contexts, read the iOS SDK 7.x to 8.0 migration guides for Swift or Objective-C and Best practices for upgrading users to contexts.
JavaScript
Expand JavaScript code sample
In the JavaScript SDK, construct a context using key/value pairs for the context attributes. Contexts use the LDContext
type. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example of a context:
const context = {kind: 'user',key: 'user-key-123abc',firstName: 'Sandy',lastName: 'Smith',email: 'sandy@example.com',groups: ['Google', 'Microsoft']};
Here's how to construct a context with a context kind of something other than "user":
const context = {kind: 'organization',key: 'org-key-123abc'};const client = LDClient.initialize('client-side-id-123abc', context);
Here's how to construct a multi-context, which includes multiple context kinds:
const deviceContext = {kind: 'device',type: 'iPad',key: 'device-key-123abc'}const userContext = {kind: 'user',key: 'user-key-123abc',name: 'Sandy',role: 'doctor'}const multiContext = {kind: 'multi',user: userContext,device: deviceContext}const client = LDClient.initialize('client-side-id-123abc', multiContext)
The optional name
and kind
attributes expect string values. If the kind
attribute is not specified, it is assumed to be "user." Other attributes can be booleans, numbers, strings, arrays, or JSON objects.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
We recommend against using personally identifiable information (PII) in context keys. If the key
attribute you rely on in your context JSON does contain PII, you should enable the useReport
option by sending the evaluation context as a JSON base64 URL-encoded path parameter. When you enable useReport
, the SDK fetches flag settings by sending the context JSON in the body of a REPORT request instead, hiding that information from request logs.
To learn how to configure private attributes in the JavaScript SDK, read Private attributes.
To learn how to configure anonymous contexts in the JavaScript SDK, read Anonymous contexts and users.
Node.js (client-side)
Expand Node.js (client-side) code sample
In the Node.js (client-side) SDK, construct a context using key/value pairs for the context attributes. Contexts use the LDContext
type. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example of a context:
const context = {kind: 'user',key: 'user-key-123abc',firstName: 'Sandy',lastName: 'Smith',email: 'sandy@example.com',groups: ['Google', 'Microsoft']};
Here's how to construct a context with a context kind of something other than "user":
const context = {kind: 'organization',key: 'org-key-123abc'};
Here's how to construct a multi-context, which includes multiple context kinds:
const deviceContext = {kind: 'device',type: 'iPad',key: 'device-key-123abc'}const userContext = {kind: 'user',key: 'user-key-123abc',name: 'Sandy',role: 'doctor'}const multiContext = {kind: 'multi',user: userContext,device: deviceContext}
The kind
and name
attributes expect string values. Other attribute values can be booleans, numbers, strings, arrays, or JSON objects.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
By default, when the SDK requests feature flags from LaunchDarkly, it makes an HTTP GET request with the user properties encoded in the URL. If you do not want keys or other properties to be in request URLs, enable the useReport
option in your client configuration. The SDK sends data in the body of an HTTP REPORT request instead.
To learn how to configure private attributes in the Node.js (client-side) SDK, read Private attributes.
To learn how to configure anonymous contexts in the Node.js (client-side) SDK, read Anonymous contexts and users.
React Native
Expand React Native code sample
In the React Native SDK, construct a context using key/value pairs for the context attributes. Contexts use the LDContext
type.
The first attribute in the object is the key
. In the React Native SDK, both key
and kind
are required. They are the only mandatory attributes. The combination of key and kind must uniquely identify each context. You can use any value for the key, such as a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
import { type LDContext } '@launchdarkly/react-native-client-sdk';// key and kind are the only required attributeslet context: LDContext = {key: 'user-key-123abc',kind: 'user',firstName: 'Sandy',lastName: 'Smith',email: 'sandy@example.com',address: {street: '123 Main St',city: 'Springfield'}};
Here's how to construct a context with a context kind of something other than "user":
const context = {kind: 'organization',key: 'org-key-123abc'};
Here's how to construct a multi-context, which includes multiple context kinds:
const deviceContext = {kind: 'device',key: 'device-key-123abc'};const userContext = {kind: 'user',key: 'user-key-123abc',name: 'Sandy',role: 'doctor'};const multiContext = {kind: 'multi',user: userContext,device: deviceContext}
If the context is anonymous, you should set the key
to an empty string. The SDK will automatically set the key to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.
Other attributes can be booleans, numbers, strings, arrays, or JSON objects.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the React Native SDK, read Private attributes.
To learn how to configure anonymous contexts in the React Native SDK, read Anonymous contexts and users.
React Web
All context-related functionality provided by the JavaScript SDK is also available in the React Web SDK.
Unlike the JavaScript SDK, the React Web SDK does not require a context object for initialization. If you do not specify one, the React SDK uses an anonymous context by default.
Roku
Expand Roku code sample
In the Roku SDK, use LaunchDarklyCreateContext
to construct a context. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
context = LaunchDarklyCreateContext({"key": "user-key-123abc", "kind": "user"})
Here's how to construct a context with a context kind of something other than "user":
context = LaunchDarklyCreateContext({"key": "org-key-123abc", "kind": "organization"})
Here's how to construct a multi-context, which includes multiple context kinds:
context = LaunchDarklyCreateContext({"kind": "multi","user": { "key": "user-key-123abc", "name": "Sandy" },"org": { "key": "org-key-789xyz", "name": "LaunchDarkly" }})
The optional name
and kind
attributes expect string values. If the kind
attribute is not specified, it is assumed to be "user." Other attributes can be booleans, numbers, strings, arrays, or JSON objects.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Roku SDK, read Private attributes.
To learn how to configure anonymous contexts in the Roku SDK, read Anonymous contexts and users.
Server-side SDKs
Here are the configuration options for contexts in server-side SDKs:
- .NET (server-side)
- Apex
- C++ (server-side)
- Erlang
- Go
- Haskell
- Java
- Lua
- Node.js (server-side)
- PHP
- Python
- Ruby
- Rust
.NET (server-side)
Expand .NET (server-side) code sample
In the server-side .NET SDK, you can construct a Context
that only has a key by calling Context.New
. The context kind defaults to "user," or you can supply a different context kind. Alternatively, you can use the Context.Builder
method for building a context with other properties.
The argument to Builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
LDContext context = Context.Builder("context-key-123abc").Set("firstName", "Sandy").Set("lastName", "Smith").Set("email", "sandy@example.com").Set("groups", LdValue.ArrayOf(LdValue.Of("Google"), LdValue.Of("Microsoft"))).Build();
Here's how to construct a context with a context kind of something other than "user":
var context2 = Context.New(ContextKind.Of("organization"), "org-key-123abc");
Here's how to construct a multi-context, which includes multiple context kinds:
var userContext = Context.New("context-key-123abc");var deviceContext = Context.Builder("device-key-123abc").Kind("device").Build();var multiContext = Context.NewMulti(userContext, deviceContext);
The optional name and kind attributes, which you can set with .Name()
and .Kind()
, expect string values. If the kind attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or JSON objects. The SDK uses the LdValue
type to represent arrays and objects. The .NET SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the .NET (server-side) SDK, read Private attributes.
To learn how to configure anonymous contexts in the .NET (server-side) SDK, read Anonymous contexts and users.
Apex
Expand Apex code sample
The Apex SDK does not support contexts. Instead, it supports users. You can think of these as contexts with a context kind of "user." Other context kinds are not supported.
Here's an example of a user:
LDUser user = new LDUser.Builder('user-key-123abc').setFirstName('Sandy').setLastName('Smith').setEmail('sandy@example.com').setCustom(new LDValueObject.Builder().set('groups', new LDValueArray.Builder().add(LDValue.of('Google')).add(LDValue.of('Microsoft')).build()).build()).build();
The argument to Builder
is the user's key. The key should uniquely identify each user. You can use a primary key or a hash, as long as the same user always has the same key. We recommend using a hash if possible. In this example, the hash is "user-key-123abc"
.
To learn how to configure private attributes in the Apex SDK, read Private attributes.
To learn how to configure anonymous users in the Apex SDK, read Anonymous contexts and users.
C++ (server-side)
Expand C++ (server-side) code sample
In the C++ (server-side) SDK, you can construct a context using the ContextBuilder
. The arguments to .Kind()
are the context kind and key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash for the key, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
auto context = ContextBuilder().Kind("user", "user-key-123abc").Set("firstName", "Sandy").Set("lastName", "Smith").Set("groups", {"Google", "Microsoft"}).Build();
Here's how to construct a context with context kind of something other than "user":
auto context = ContextBuilder().Kind("organization", "org-key-123abc").Build();
Here's how to construct a multi-context, which includes multiple context kinds:
auto context = ContextBuilder().Kind("user", "user-key-123abc").Name("Sandy").Kind("organization", "org-key-123abc").Name("Global Health Services").Build();
If you are working in C, when you are done with the context ensure that you free the structure:
LDContext_Free(context);
To learn how to configure private attributes in the C++ (server-side) SDK, read Private attributes.
To learn how to configure anonymous contexts in the C++ (server-side) SDK, read Anonymous contexts and users.
Erlang
Expand Erlang code sample
In the Erlang SDK, use ldclient_context:set
and ldclient_context:new
to define and construct a context.
The key
property is the context's key. The key is the only mandatory context attribute. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
You can set the kind, or, if you do not set it, LaunchDarkly assumes that the context kind is "user."
Here's an example of a context:
Context = ldclient_context:set(<<"name">>, <<"Sandy Smith">>,ldclient_context:set(<<"email">>, <<"sandy@example.com">>,ldclient_context:set(<<"group">>, [<<"microsoft">>, <<"google">>],ldclient_context:new(<<"user-key-abc123">>, <<"user">>)))),
Here's how to construct a context with a context kind of something other than "user":
Context = ldclient_context:new(<<"org-key-123abc">>, <<"organization">>)%% Or as a mapContext = #{kind => <<"organization">>, key => <<"org-key-123abc">>}
Here's how to construct a multi-context, which includes multiple context kinds:
Context = ldclient_context:new_multi_from([%% Using `new/1` creates a context with a kind of <<"user">>.ldclient_context:new(<<"user-key-123abc">>),%% Using `new/2` creates a context of the specified kind (<<"device">>).ldclient_context:new(<<"device-key-123abc">>, <<"device">>)]). %% kind = device
To learn how to configure private attributes in the Erlang SDK, read Private attributes.
To learn how to configure anonymous contexts in the Erlang SDK, read Anonymous contexts and users.
Go
Expand Go code sample
The Go SDK defines a Context
struct and a Builder
. The context key
is the only mandatory context attribute. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
import ("github.com/launchdarkly/go-sdk-common/v3/ldcontext""github.com/launchdarkly/go-sdk-common/v3/ldvalue")// Context with only a key// by default, the context kind is "user"context1 := ldcontext.New("context-key-123abc")// Context with a key plus other attributescontext2 := ldcontext.NewBuilder("context-key-456def").Kind("organization").Name("Global Health Services").SetString("email", "info@globalhealthexample.com").SetValue("address", ldvalue.ObjectBuild().SetString("street", "123 Main Street").SetString("city", "Springfield")).SetValue("groups", ldvalue.ArrayOf(ldvalue.String("Google"), ldvalue.String("Microsoft"))).Build()
Here's how to construct a context with a context kind of something other than "user":
context1 := ldcontext.NewWithKind("organization", "org-key-123abc")
Here's how to construct a multi-context, which includes multiple context kinds:
multiContext := ldcontext.NewMulti(ldcontext.New("user-key-123abc"),ldcontext.NewWithKind("device", "device-key-123abc"))
Each individual context within a multi-context can have the same attributes. The only restriction is that each context has to have a different context kind
from the others within the multi-context.
You can also use the context builder to create each of the individual contexts:
multiContext := ldcontext.NewMulti(ldcontext.NewBuilder("user-key-123abc").Name("Sandy").Build(),ldcontext.NewBuilder("device-key-123abc").Kind("device").Name("iPad").Build(),)
To learn more about the available attributes, read Context
and Builder
.
The kind and name attributes expect string values. You can set the kind, or, if you do not set it, LaunchDarkly assumes that the context kind is "user." Other attribute values can be booleans, numbers, strings, arrays, or JSON objects. These types are all represented by the ldvalue.Value
type. The Go SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Go SDK, read Private attributes.
To learn how to configure anonymous contexts in the Go SDK, read Anonymous contexts and users.
Haskell
Expand Haskell code sample
In the Haskell SDK, use makeContext
to create a new context. The argument to makeContext
is the context's key. The key is the only mandatory attribute. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example of a context:
{-# LANGUAGE OverloadedStrings #-}import LaunchDarkly.Server.Contextimport Data.Function ((&))-- Context with key and kindcontext1 :: Contextcontext1 = makeContext "context-key-123abc" "user"-- Context with a key plus other attributescontext2 :: Contextcontext2 = makeContext "context-key-456def" "organization"& withAttribute "name" "Global Health Services"& withAttribute "email" "info@globalhealthexample.com"& withAttribute "address" $ Object $ fromList [("street", "123 Main St"), ("city", "Springfield")]
Here's how to construct a context with a context kind of something other than "user":
makeContext "context-key-123abc" "organization"
Here's how to construct a multi-context, which includes multiple context kinds:
makeMultiContext [ makeContext "user-key-123abc" "user", makeContext "device-key-123abc" "device"]
To learn how to configure private attributes in the Haskell SDK, read Private attributes.
To learn how to configure anonymous contexts in the Haskell SDK, read Anonymous contexts and users.
Java
Expand Java code sample
In the Java SDK, use a builder pattern to construct contexts. The argument to Builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
LDContext context = LDContext.builder("context-key-123abc").set("firstName", "Sandy").set("lastName", "Smith").set("email", "sandy@example.com").set("groups",LDValue.buildArray().add("Google").add("Microsoft").build()).build();
Here's how to construct a context with a context kind of something other than "user":
LDContext context1 = LDContext.create(ContextKind.of("organization"), "org-key-123abc");
Here's how to construct a multi-context, which includes multiple context kinds:
LDContext multiContext = LDContext.createMulti(LDContext.create("user-key-123abc"),LDContext.create(ContextKind.of("device"), "device-key-123abc"));
The documentation for ContextBuilder
shows you all the attributes that LaunchDarkly supports by default.
The optional name and kind attributes expect string values. If the "kind" attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or objects. If you pass a value that looks like a number or a boolean, the SDK interprets it that way. The Java SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Java SDK, read Private attributes.
To learn how to configure anonymous contexts in the Java SDK, read Anonymous contexts and users.
Lua
Expand Lua code sample
In the Lua SDK, use makeContext
to construct a context of any kind. This requires a context key
. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible. The context attributes are defined as part of the context kind
.
To construct a user context specifically, you can use makeUser
. Both makeUser
and makeContext
require a context key. You can omit the kind
option if you construct your context with makeUser
. This method is a convenience to make upgrading from the Lua SDK version 1.x to version 2.0 easier. It is deprecated and may be removed in future versions.
Here's an example of a context:
-- using makeContextlocal user1 = ld.makeContext({user = {key = "user1-key-123abc",attributes = {firstName = "Sandy",lastName = "Smith",email = "sandy@example.com",groups = { "Google", "Microsoft" }}}})-- using makeUser, which is deprecated,-- to create an identical context (with unique key)local user2 = ld.makeUser({key = "user2-key-123abc",firstName = "Sandy",lastName = "Smith",email = "sandy@example.com",custom = {groups = { "Google", "Microsoft" }}})-- using makeContext to create a different kind of contextlocal orgContext = ld.makeContext({organization = {key = "org-key-123abc",name = "Global Health Services"}})
Here's how to construct a context with a context kind of something other than "user":
-- using makeContext to create a different kind of contextlocal orgContext = ld.makeContext({organization = {key = "org-key-123abc",name = "Global Health Services"}})
Here's how to construct a multi-context, which includes multiple context kinds:
-- using makeContext to create a multi-contextlocal context = ld.makeContext({user = {key = "user-key-123abc"},org = {key = "org-key-123abc"}})
To learn more, read makeUser
and makeContext
.
To learn how to configure private attributes in the Lua SDK, read Private attributes.
To learn how to configure anonymous contexts in the Lua SDK, read Anonymous contexts and users.
Node.js (server-side)
Expand Node.js (server-side) code sample
In the Node.js (server-side) SDK, contexts are JSON objects. The key
property is the context key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
const ld = require('@launchdarkly/node-server-sdk');const context: ld.LDContext = {kind: 'user',key: 'user-key-123abc',firstName: 'Sandy',lastName: 'Smith',email: 'sandy@example.com',groups: ['Google', 'Microsoft'],};
Here's how to construct a context with a context kind of something other than "user":
const context = {kind: 'device',key: 'device-key-123abc'}
Here's how to construct a multi-context, which includes multiple context kinds:
const context = {kind: 'multi',user: { key: 'user-key-123abc' },device: { key: 'device-key-123abc' }}
The optional name
and kind
attributes expect string values. If the kind
attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or JSON objects.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Node.js (server-side) SDK, read Private attributes.
To learn how to configure anonymous contexts in the Node.js (server-side) SDK, read Anonymous contexts and users.
PHP
Expand PHP code sample
In the PHP SDK, use a builder pattern to construct contexts. The first argument to LDContextBuilder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
$context = LDContext::builder("context-key-123abc")->set("firstName", "Sandy")->set("lastName", "Smith")->set("email", "sandy@example.com")->set("groups", ["Google", "Microsoft"])->build();
Here's how to construct a context with a context kind of something other than "user":
$context = LDContext::create("context-key-123abc", "organization");
Here's how to construct a multi-context, which includes multiple context kinds:
$deviceContext = LDContext::create("device-key-123abc", "device");$orgContext = LDContext::create("org-key-123abc", "org");$multiContext = LDContext::createMulti($deviceContext, $orgContext);
The kind and name attributes expect string values. Other attribute values can be booleans, numbers, strings, or arrays. If you enter a custom value on the Contexts list that looks like a number or a boolean, the SDK interprets it that way. The PHP SDK is strongly-typed, so be aware of this distinction.
To learn how to configure private attributes in the PHP SDK, read Private attributes.
To learn how to configure anonymous contexts in the PHP SDK, read Anonymous contexts and users.
Python
Expand Python code sample
In version 8.0 and higher of the Python SDK, the Context
class has a create
method for creating a context with a context kind of "user" and with only a key. It has a builder
method for building a context with other properties.
The argument to Context.builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
context = Context.builder("context-key-123abc") \.set("firstName", "Sandy") \.set("lastName", "Smith") \.set("email", "sandy@example.com") \.set("groups", ["Google", "Microsoft"]) \.build()
Here's how to construct a context with a context kind of something other than "user":
context1 = Context.create("org-key-123abc", "organization")
Here's how to construct a multi-context, which includes multiple context kinds:
multi_context = Context.create_multi(Context.create("user-key-123abc"),Context.create("device-key-123abc", "device"))
If you have many attributes to set, you can also create a context from a dictionary:
pre_existing_dict = {'key': 'context-key-123abc','kind': 'user','firstName': 'Sandy','lastName': 'Smith','email': 'sandy@example.com','groups': ['Google', 'Microsoft'],}context = Context.from_dict(pre_existing_dict)
The optional name and kind attributes expect string values. If the "kind" attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or objects.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn more, read from_dict
.
To learn how to configure private attributes in the Python SDK, read Private attributes.
To learn how to configure anonymous contexts in the Python SDK, read Anonymous contexts and users.
Ruby
Expand Ruby code sample
In the Ruby SDK, contexts are instances of LaunchDarkly::LDContext
. Legacy users can continue to be provided as simple hashes.
The key
property is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key, an email address, or a hash string, as long as the same context always has the same key. We recommend using a hash string if possible.
Here's an example:
context = LaunchDarkly::LDContext.create({key: "user-key-123abc",kind: "user",firstName: "Sandy",lastName: "Smith",email: "sandy@example.com",groups: ["Google", "Microsoft"]})
Here's how to construct a context with a context kind of something other than "user":
context = LaunchDarkly::LDContext.with_key("context-key-123abc", "organization")
Here's how to construct a multi-context, which includes multiple context kinds:
multi_context = LaunchDarkly::LDContext.create_multi([LaunchDarkly::LDContext.with_key("user-key-123abc"),LaunchDarkly::LDContext.with_key("device-key-123abc", "device"),])
All context attribute keys, for both built-in and custom attributes, must be symbols and not strings.
The optional name and kind attributes expect string values. If the "kind" attribute is not specified, it is assumed to be "user" and the hash is assumed to be in the legacy user format. Other attribute values can be booleans, numbers, strings, arrays, or objects. If you enter a custom value on the Contexts list that looks like a number or a boolean, the SDK interprets it that way.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Ruby SDK, read Private attributes.
To learn how to configure anonymous contexts in the Ruby SDK, read Anonymous contexts and users.
Rust
Expand Rust code sample
The Rust SDK defines a Context
struct and a ContextBuilder
.
The context key
is the only mandatory context attribute. You can set the kind, or, if you do not set it, LaunchDarkly assumes that the context kind is "user." The combination of key and kind must uniquely identify each context. For the key, you can use a primary key, a hash string, or some other value, as long as the same context always has the same key. We recommend using a hash string if possible.
Here's an example:
// Context with only a keylet context = ContextBuilder::new("context-key-123abc").build()?;// Context with a key plus other attributeslet custom = hashmap! {"groups".into() => vec!["Google", "Microsoft"].into(),};let context = ContextBuilder::new("context-key-123abc").set_value("first_name", "Sandy".into()).set_value("last_name", "Smith".into()).set_value("email", "sandy@example.com".into()).set_value("Google", "groups".into()).set_value("Microsoft", "groups".into()).build();
Here's how to construct a context with a context kind of something other than "user":
let context = ContextBuilder::new("context-key-123abc").kind("organization").build()?;
Here's how to construct a multi-context, which includes multiple context kinds:
let user_context = ContextBuilder::new("user-key-123abc").build()?;client.identify(user_context.clone());let device_context = ContextBuilder::new("device-key-123abc").kind("device").build()?;client.identify(device_context.clone());let multi_context = MultiContextBuilder::new().add_context(user_context).add_context(device_context).build()?;client.identify(multi_context);
To learn more about the available attributes, read Context
and ContextBuilder
.
The optional name and kind attributes, which you can set with .name()
and .kind()
, expect string values. Other attribute values can be any JSON type, including booleans, numbers, strings, arrays, or objects. These types are all represented by the AttributeValue
type. The Rust SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your flag or segment targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting. To learn more, read Target with flags.
To learn how to configure private attributes in the Rust SDK, read Private attributes.
To learn how to configure anonymous contexts in the Rust SDK, read Anonymous contexts and users.
Edge SDKs
Here are the configuration options for contexts in edge SDKs.
Akamai
Expand Akamai code sample
To configure contexts, the Akamai SDK uses the same code as the Node.js server-side SDK.
The Akamai SDK does not support sending events, so private attributes are not supported.
Cloudflare
Expand Cloudflare code sample
To configure contexts, the Cloudflare SDK uses the same code as the Node.js server-side SDK.
Vercel
Expand Vercel code sample
To configure contexts, the Vercel SDK uses the same code as the Node.js server-side SDK.
AI SDKs
Here are the configuration options for contexts in AI SDKs:
.NET (AI)
Expand .NET (AI) code sample
In the .NET (AI) SDK, you can construct a Context
that only has a key by calling Context.New
. The context kind defaults to "user," or you can supply a different context kind. Alternatively, you can use the Context.Builder
method for building a context with other properties.
The argument to Builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
LDContext context = Context.Builder("context-key-123abc").Set("firstName", "Sandy").Set("lastName", "Smith").Set("email", "sandy@example.com").Set("groups", LdValue.ArrayOf(LdValue.Of("Google"), LdValue.Of("Microsoft"))).Build();
Here's how to construct a context with a context kind of something other than "user":
var context2 = Context.New(ContextKind.Of("organization"), "org-key-123abc");
Here's how to construct a multi-context, which includes multiple context kinds:
var userContext = Context.New("context-key-123abc");var deviceContext = Context.Builder("device-key-123abc").Kind("device").Build();var multiContext = Context.NewMulti(userContext, deviceContext);
The optional name and kind attributes, which you can set with .Name()
and .Kind()
, expect string values. If the kind attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or JSON objects. The SDK uses the LdValue
type to represent arrays and objects. The .NET SDK is strongly-typed, so be aware of this distinction.
If an attribute is a JSON object, then in your AI config targeting, you can use /
as a delimiter to refer to specific object fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting rules. You can use .
as a delimiter in your AI config prompt. Continuing the same example, you could use {{ldctx.address.city}}
in your prompt, and the value of the "city" field will be substituted when you customize the AI config. To learn more, read Target with flags and Customizing AI configs.
To learn how to configure private attributes in the .NET (AI) SDK, read Private attributes.
To learn how to configure anonymous contexts in the .NET (AI) SDK, read Anonymous contexts and users.
Node.js (AI)
Expand Node.js (AI) code sample
In the Node.js (AI) SDK, contexts are JSON objects. The key
property is the context key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
const context: LDContext = {kind: 'user',key: 'user-key-123abc',firstName: 'Sandy',lastName: 'Smith',email: 'sandy@example.com',groups: ['Google', 'Microsoft'],};
Here's how to construct a context with a context kind of something other than "user":
const context: LDContext = {kind: 'device',key: 'device-key-123abc'}
Here's how to construct a multi-context, which includes multiple context kinds:
const context: LDContext = {kind: 'multi',user: { key: 'user-key-123abc' },device: { key: 'device-key-123abc' }}
The optional name
and kind
attributes expect string values. If the kind
attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or JSON objects.
If an attribute is a JSON object, then in your AI config targeting, you can use /
as a delimiter to refer to specific fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting rules. You can use .
as a delimiter in your AI config prompt. Continuing the same example, you could use {{ldctx.address.city}}
in your prompt, and the value of the "city" field will be substituted when you customize the AI config. To learn more, read Target with AI configs and Customizing AI configs.
To learn how to configure private attributes in the Node.js (AI) SDK, read Private attributes.
To learn how to configure anonymous contexts in the Node.js (AI) SDK, read Anonymous contexts and users.
Python (AI)
Expand Python (AI) code sample
In the Python (AI) SDK, the Context
class has a create
method for creating a context with a context kind of "user" and with only a key. It has a builder
method for building a context with other properties.
The argument to Context.builder
is the context's key. The combination of key and kind must uniquely identify each context. For the key, you can use a primary key or a hash, as long as the same context always has the same key. We recommend using a hash if possible.
Here's an example:
context = Context.builder("context-key-123abc") \.set("firstName", "Sandy") \.set("lastName", "Smith") \.set("email", "sandy@example.com") \.set("groups", ["Google", "Microsoft"]) \.build()
Here's how to construct a context with a context kind of something other than "user":
context1 = Context.create("org-key-123abc", "organization")
Here's how to construct a multi-context, which includes multiple context kinds:
multi_context = Context.create_multi(Context.create("user-key-123abc"),Context.create("device-key-123abc", "device"))
If you have many attributes to set, you can also create a context from a dictionary:
pre_existing_dict = {'key': 'context-key-123abc','kind': 'user','firstName': 'Sandy','lastName': 'Smith','email': 'sandy@example.com','groups': ['Google', 'Microsoft'],}context = Context.from_dict(pre_existing_dict)
The optional name and kind attributes expect string values. If the "kind" attribute is not specified, it is assumed to be "user." Other attribute values can be booleans, numbers, strings, arrays, or objects.
If an attribute is a JSON object, then in your AI config targeting, you can use /
as a delimiter to refer to specific fields. For example, if you have an "address" attribute that includes several fields, then you could use /address/city
in your targeting rules. You can use .
as a delimiter in your AI config prompt. Continuing the sam example, you could use {{LDCTX.address.city}}
in your prompt, and the value of the "city" field will be substituted when you customize the AI config. To learn more, read Target with AI configs and Customizing AI configs.
To learn how to configure private attributes in the Python (AI) SDK, read Private attributes.
To learn how to configure anonymous contexts in the Python (AI) SDK, read Anonymous contexts and users.