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

Identifying and changing contexts

Read time: 24 minutes
Last edited: Jun 21, 2024

Overview

This topic explains how to use the identify feature in LaunchDarkly SDKs. Identify is available for client-side and server-side SDKs.

Newer versions of LaunchDarkly SDKs replace users with contexts

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.

Creating contexts and evaluating flags based on them is supported in the latest major versions of most of our SDKs. For these SDKs, the code samples on this page include the two most recent versions.

Using identify to change contexts and users

The identify feature's behavior differs between client-side and server-side SDKs.

Client-side SDKs are configured to operate for one end user at a time, identified or anonymous. In these SDKs, the identify feature allows you to change the context, such as when an end user logs in or changes their settings. Identifying contexts and users causes LaunchDarkly to index them.

To associate two contexts with each other, such as your representations of an end user before and after they log in, call identify with a multi-context that contains both contexts. The association between the two contexts that comprise your multi-context doesn't persist between sessions. You must call identify with the multi-context each time.

Here is an example of a multi-context:

"context": {
"kind": "multi",
"user": {
"key": "user-key-123abc",
"name": "Sandy",
"email": "sandy@example.com",
},
"device": {
"key": "device-key-123abc",
"type": "iPhone",
"deviceId": 12345
}
}

Server-side SDKs operate for multiple end users concurrently. Unlike in client-side SDKs, server-side SDKs do not have a notion of "changing the user context" because contexts or users are directly passed to client method invocations for actions such as evaluating flag variations. In server-side SDKs, the only impact of identifying contexts and users is that they are added to the Contexts list. However, in most applications this is not needed because they are automatically indexed when used for a flag evaluation. Instead, you should provide the evaluation object in a variation or all flags call to get the expected flag evaluation. To learn more, read Evaluating flags and Getting all flags.

To learn more about the differences in how SDKs identify and use users and contexts, read Client-side, server-side, and edge SDKs.

Details about each SDK's identify feature are available in the SDK-specific sections below.

  • Client-side SDKs
  • Server-side SDKs

Client-side SDKs

This feature is available in the following client-side SDKs:

.NET (client-side)

Expand .NET (client-side) code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify method tells the client to change the current context and obtain the feature flag values for the new context. In the .NET SDK, you can use either the Identify or IdentifyAsync method to switch contexts.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call Identify() or IdentifyAsync() so that the person receives the correct feature flag settings for their account.

In general, however, we recommend composing the new context as a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call Identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

You may want to wait until the flag values for the new context have been loaded before proceeding. You can do this either by calling the synchronous method Identify with a timeout, or by calling the asynchronous method IdentifyAsync and awaiting the result.

Here's how:

var updatedContext = Context.Builder("context-key-123abc")
.Set("email", "sandy@example.com")
.Build();
// Synchronous method
client.Identify(updatedContext, TimeSpan.FromSeconds(5));
// Asynchronous method
await client.IdentifyAsync(updatedContext);

To learn more, read Identify and IdentifyAsync.

Android

Expand Android code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

Here's how:

LDContext updatedContext = LDContext.builderFromContext(context)
.email("sandy@example.com")
.build();
client.identify(updatedContext);

The identify() call loads any saved flag values for the new user context and immediately triggers an update of the latest flags from LaunchDarkly.

identify() returns a Future to indicate completion. If you want to be sure subsequent code is using the latest values from the server, you can wait for the Future using get.

To learn more, read identify.

C++ (client-side)

Expand C++ (client-side) code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call Identify so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call Identify with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

Here's how to update your initial context when you have additional information:

/* before end user logs in */
auto context = ContextBuilder()
.Kind("device", "device-key-123abc")
.Build();
/* after end user logs in */
auto updated_context = ContextBuilder(context)
.Kind("user", "user-key-123abc")
.Name("Sandy")
.Kind("organization", "org-key-123abc")
.Name("Global Health Services")
.Build();

After you update the context, you must call identify with the updated context in order to evaluate flags based on the updated information.

Here's how to use the identify method to switch contexts:

client.IdentifyAsync(updated_context);

You can also examine the result to determine if the identification succeeded. Here's how:

auto identify_result = client.IdentifyAsync(updated_context);
auto status = identify_result.wait_for(maxwait);
if (status == std::future_status::ready) {
/* The client's attempt to identify succeeded or failed in the specified amount of time. */
if (identify_result.get()) {
/* Identification succeeded */
} else {
/* Identification failed */
}
} else {
/* The specified timeout was reached, but the client is still identifying. */
}

The IdentifyAsync call loads any saved flag values for the new context and immediately triggers an update of the latest flags from LaunchDarkly. Because this method re-fetches flag settings for the updated context, you should not call it at high frequency. The intended use case for switching contexts is the login/logout flow. To learn more, read IdentifyAsync.

Electron

Expand Electron code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current user and obtain the feature flag values for the new user.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

Here's how:

const newUser = { key: 'user-key-123abc', name: 'Sandy' };
client.identify(newUser, (newFlags) => {
console.log('value of flag for this user is: ' + newFlags['flag-key-123abc']);
console.log('this should be the same: ' + client.variation('flag-key-123abc'));
});
// or:
client.identify(newUser).then((newFlags) => {
// as above
});

To learn more, read identify.

Flutter

Expand Flutter code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

Here's how:

final updatedContext = LDContextBuilder()
.kind('user', 'user-key-123abc')
.setString('email', 'sandy@example.com'))
.build();
await client.identify(updatedContext);

To learn more, read identify.

iOS

Expand iOS code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

If the client app does not identify an LDContext, LDClient creates an anonymous default context, which can affect which feature flags LaunchDarkly delivers to the LDClient. Client apps should follow the Apple Privacy Policy when collecting end user information.

Here's how:

let newContext = try LDContextBuilder(key: "context-key-123abc").build().get();
// You can also call identify with a completion
LDClient.get()!.identify(context: newContext) {
// Flags have been retrieved for the new context
}

To learn more, read identify.

JavaScript

Expand JavaScript code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

If you provide a callback function, it is called with a map of flag keys and values after the flag values for the new context are available. After that point, variation() uses the new values. You can also use a Promise for the same purpose.

Here's how:

client.identify(newContext, hash, function() {
console.log("New context's flags available");
});

To learn more, read identify.

If your contexts are extraordinarily large, you may need to configure the JavaScript SDK to send the evaluation context as a request body. To learn more, read Using REPORT in the JavaScript SDK.

You must use a hash parameter while in secure mode

The hash parameter is the hash for the new context, assuming that the context's key has changed. The hash parameter is only required in secure mode. If secure mode is not enabled, pass in null for the hash.

Node.js (client-side)

Expand Node.js (client-side) code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current user and obtain the feature flag values for the new user.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

Here's how:

client.identify(newContext, () => {
console.log("New context's flags available");
});
// or, with a Promise:
client.identify(newContext).then(() => {
console.log("New context's flags available");
});

To learn more, read identify.

React

Expand React code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

Here's how:

import { useLDClient } from 'launchdarkly-react-client-sdk';
let ldClient = useLDClient();
ldClient.identify(newContext, null, () => {
console.log("New context's flags available");
});

To learn more, read identify.

React Native

Expand React Native code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify method tells the client to change the current context and obtain the feature flag values for the new context.

Version 10 requires an identify call

In the React Native SDK version 10, you do not provide a context when you initialize the ReactNativeLDClient. You must call identify before you can evaluate a feature flag for a specific context. End users will receive fallback values until you call specify a context by calling identify.

If multiple customers use your app on a single device, you may want to change contexts and have separate flag settings for each one. To do this, the SDK stores contexts on a single device using react-native-async-storage, and supports switching between different contexts. You can use the identify method to switch contexts. identify loads any saved flag values for the new context and immediately triggers an update of the latest flags from LaunchDarkly.

You might also call identify when your app gathers additional information about the end user. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user. Then you can evaluate flags using attributes from all three context kinds together.

Here's how:

import { useLDClient } from '@launchdarkly/react-native-client-sdk';
const client = useLDClient();
const context: LDContext = {'key': 'user-key-123abc', 'kind': 'user'};
client
.identify(context)
.catch((e: any) => console.error(`error identifying ${context.key}: ${e}`));

To learn more, read identify.

Roku

Expand Roku code sample

Client-side SDKs are configured to operate for one context at a time, whether identified or anonymous. The identify() method tells the client to change the current context and obtain the feature flag values for the new context.

In some situations, the new context may be an updated version of the existing context. For example, on a sign-in page in a single-page app, you could represent the same person as a multi-context that combines a pre-login anonymous context and a post-login context with the "user" kind. After the person logs in, you can call identify() so that the person receives the correct feature flag settings for their account.

In other situations, the new context may be a multi-context based on multiple identifiers, rather than only pre- and post-login contexts. For example, as soon as an end user visits your app, you may initialize the client with a context using a context kind of "device." When the end user logs in, you now also have their user and organization information. You can call identify() with a multi-context that contains the "device," "user," and "organization" contexts for the end user.

To do this:

' before the end user logs in
device = {
"kind": "device",
"key": "device-key-123abc",
"type": "tablet"
}
context = LaunchDarklyCreateContext(device)
' after the end user logs in
multi = {
"kind": "multi",
"device": device,
"user": {"key": "user-key-123abc", "name": "Sandy"},
"organization": {"key": "org-key-123abc", "name": "Acme, Inc."}
}
launchDarkly.identify(multi)

Server-side SDKs

This feature is available in the following server-side SDKs:

.NET (server-side)

Expand .NET (server-side) code sample

In server-side SDKs, Identify creates or updates contexts on LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call Identify. The Variation methods automatically create contexts on the Contexts list for you, using the context you pass to each Variation method. Identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use Identify:

client.Identify(context);

To learn more, read Identify.

Apex

Expand Apex code sample

In server-side SDKs, identify creates or updates users in LaunchDarkly, which makes them available for targeting and autocomplete on the Users list.

To use identify:

client.identify(user);

To learn more, read Other methods.

C++ (server-side)

Expand C++ (server-side) code sample

In server-side SDKs, Identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call Identify. The variation call automatically creates contexts on the Contexts list for you, using the evaluation context you pass to each variation method. Identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use Identify:

client.Identify(context);

To learn more, read Identify() in Client.

Erlang

Expand Erlang code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation methods automatically create contexts on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

ldclient:identify(#{key => <<"context-key-123abc">>})

To learn more, read identify.

Go

Expand Go code sample

In server-side SDKs, Identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call Identify. The Variation method automatically creates contexts on the Contexts list for you, using the context you pass to each Variation method. Identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use Identify:

client.Identify(context)

To learn more, read Identify.

Haskell

Expand Haskell code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation methods automatically create contexts on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

identify client context

To learn more, read identify.

Java

Expand Java code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation methods automatically create contexts on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

client.identify(context);

To learn more, read identify.

Lua

Expand Lua code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation methods automatically create contexts on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

client:identify(context)

To learn more, read identify.

Node.js (server-side)

Expand Node.js (server-side) code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation call automatically creates users on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

client.identify(context);

To learn more, read identify.

PHP

Expand PHP code sample

In server-side SDKs, identify creates or updates users in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation call automatically creates contexts on the Contexts list for you, using the context you pass to each variation call. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

$client->identify($context);

To learn more, read identify.

Python

Expand Python code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation method automatically creates contexts on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

ldclient.get().identify(context)

To learn more, read identify.

Ruby

Expand Ruby code sample

In server-side SDKs, identify creates or updates contexts in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation call automatically creates contexts on the Contexts list for you, using the context you pass to each variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

client.identify(context)

To learn more, read identify.

Rust

Expand Rust code sample

In server-side SDKs, identify creates or updates users in LaunchDarkly, which makes them available for targeting and autocomplete on the Contexts list.

In most cases, you do not need to call identify. The variation methods automatically create users or contexts on the Contexts list for you, using the context you pass to each Variation method. identify is useful if you want to pre-populate your Contexts list before you launch any features.

To use identify:

client.identify(context);

To learn more, read identify.