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, though each SDK sends context data to LaunchDarkly in a slightly different format:When to call identify
The timing of your identify calls determines which flag values your application receives, and how much network traffic the SDK generates. This section describes the recommended patterns for calling identify in client-side SDKs, followed by guidance for server-side SDKs.Initialize with the context you know
If you know the context when your application starts, such as when an end user is already logged in, initialize the SDK with that context. You do not need to call identify afterward. If you do not know the context when your application starts, initialize the SDK with an anonymous context. Then call identify when the context becomes available. Always give each anonymous context a unique key, or let the SDK generate one for you. If all of your anonymous contexts share the same key, then percentage rollouts, Experimentation, and individual targeting do not work as expected. To learn more, read Anonymous contexts. The React Native SDK version 10 is an exception to this rule. You do not provide a context when you initialize this SDK. Instead, you must call identify before you can evaluate flags for a context. To learn more, read React Native.Call identify when the context changes
Call identify when the context changes, such as when:- An end user logs in or logs out.
- Your application learns more about the end user, such as their organization.
- The value of an attribute that you use in targeting changes.
Use one client instance
Create one SDK client instance for each LaunchDarkly environment that your application uses, and reuse that instance. To change the context, call identify on the existing client. Do not close the client and initialize a new one, because a new client must connect to LaunchDarkly and retrieve flag values again before it is ready. To learn more, read Correctly implementing the singleton pattern.Wait for identify to complete
After you call identify to change contexts, the SDK loads flag values for the new context. Until that load completes, it is possible that flag evaluations return values that LaunchDarkly served for the previous context. The exact behavior differs between SDKs. Some SDKs keep the previous context’s flag values in memory, or read them from local storage, until the new values arrive. If your application must not use the previous context’s flag values, wait for the identify call to complete before you evaluate flags. This is especially important for flags that control access to a feature or that are part of an experiment. Depending on the SDK, you can await the result, pass a completion callback, or wait on aFuture.
If your application waits for identify before it displays content, set a timeout to prevent a slow network connection from blocking your application. After the timeout expires, the identify call keeps running, and the SDK updates the flag values when it completes. Plan what your application does until then, such as displaying content based on the flag values the SDK already has. Some SDKs recommend a timeout of less than 15 seconds, and log a message if you set a longer one.
Avoid overlapping identify calls
If you call identify again before an earlier identify call completes, some SDKs discard the intermediate calls and identify only the most recent context. A discarded call reports a “shed” or “superseded” result instead of a “completed” result. Other SDKs queue identify calls and complete them in order. If your code depends on each identify call completing, wait for each call to complete before you start the next one. To learn how your SDK handles overlapping calls, read the SDK-specific sections below.Call identify sparingly in server-side SDKs
In server-side SDKs, pass the context to each flag evaluation call. Do not call identify for each request. Flag evaluations already add contexts to the Contexts list. Calling identify for each request only sends additional events to LaunchDarkly. Call identify only when you want to add contexts to the Contexts list before you evaluate flags for them. Initialize only one SDK client instance when your application starts, and reuse it for the lifetime of the process.Client-side SDKs
This feature is available in the following client-side SDKs:- .NET (client-side)
- Android
- C++ (client-side)
- Electron
- Flutter
- iOS
- JavaScript
- Node.js (client-side)
- React
- React Native
- Roku
- Vue
.NET (client-side)
Expand .NET (client-side) code sample
Expand .NET (client-side) code sample
Identify or IdentifyAsync method to switch contexts.To wait until the flag values for the new context have been loaded before proceeding, call the synchronous method Identify with a timeout, or call the asynchronous method IdentifyAsync and await the result.Here’s how:Identify and IdentifyAsync.Android
Expand Android code sample
Expand Android code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.Here’s how: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 avoid blocking indefinitely, call get with a timeout, such as get(5, TimeUnit.SECONDS).To learn more, read identify.C++ (client-side)
Expand C++ (client-side) code sample
Expand C++ (client-side) code sample
IdentifyAsync call loads any saved flag values for the new context and immediately triggers an update of the latest flags from LaunchDarkly. To learn more, read IdentifyAsync.Electron
Expand Electron code sample
Expand Electron code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.Here’s how:identify.Flutter
Expand Flutter code sample
Expand Flutter code sample
identify method tells the client to change the current context and obtain the feature flag values for the new context.Here’s how:identify returns an IdentifyResult. If you call identify while an earlier call is in progress, the SDK holds the new call until the earlier one completes. If you call identify again before the held call starts, the new call replaces it. A replaced call returns IdentifySuperseded.To learn more, read identify.iOS
Expand iOS code sample
Expand iOS code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.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:identify(context:completion:) and identify(context:timeout:completion:) methods pass an IdentifyResult to the completion. The result is .complete, .error, .shed, or .timeout. The Swift example uses identify(context:timeout:completion:) to make sure the completion runs within five seconds. The identify request continues after the timeout expires.The SDK processes one identify request at a time. If you call identify(context:completion:) while a request is in flight, the SDK holds the new request. If you call it again before the held request starts, the new request replaces the held one, and the held request reports .shed. The Objective-C identifyWithContext:completion: method, and the deprecated Swift version of identify(context:completion:) whose completion takes no arguments, do not shed requests.To learn more, read identify.JavaScript
Expand JavaScript code sample
Expand JavaScript code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.In version 3 of the JavaScript SDK, 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. When you use a Promise, it is important that you handle the rejection case. Otherwise, it will become an unhandled Promise rejection, which is a serious error on some platforms.It is possible that the identify() call will fail. If you are using a callback, the callback will receive an error value, and calls to evaluate a flag will still return flag values for the previous context.Here’s how to identify a new context:identify.In version 4 of the JavaScript SDK, identify() returns a promise that resolves to a result object, and the promise is never rejected. The result’s status is completed, error, timeout, or shed. You can pass identify options as the second argument, including hash for secure mode and timeout, in seconds, which defaults to five seconds.By default, identify calls are sheddable in version 4. If you call identify() again before an earlier call completes, the SDK discards the intermediate calls and identifies only the most recent context. A discarded call resolves with a status of shed. To queue identify calls and complete them in order instead, set the sheddable option to false.Here’s how to identify a new context in version 4:LDIdentifyOptions.If you are using the LaunchDarkly observability SDKs, calling identify() also automatically indexes your sessions. You can then search for sessions based on context attributes.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.Node.js (client-side)
Expand Node.js (client-side) code sample
Expand Node.js (client-side) code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.Here’s how:identify.In version 4 of the Node.js (client-side) SDK, identify() returns a promise that resolves to a result object, and the promise is never rejected. The result’s status is completed, error, timeout, or shed. You can pass identify options as the second argument, including hash for secure mode and timeout, in seconds, which defaults to five seconds.By default, identify calls are sheddable in version 4. If you call identify() again before an earlier call completes, the SDK discards the intermediate calls and identifies only the most recent context. A discarded call resolves with a status of shed. To queue identify calls and complete them in order instead, set the sheddable option to false.Here’s how to identify a new context in version 4:identify.React
Expand React code sample
Expand React code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.Here’s how:identify.In version 4 of the React Web SDK, identify() returns a promise that resolves to a result object, and the promise is never rejected. The result’s status is completed, error, timeout, or shed. By default, identify calls are sheddable. If you call identify() again before an earlier call completes, the SDK discards the intermediate calls and identifies only the most recent context. To queue identify calls and complete them in order instead, set the sheddable identify option to false. To learn more, read Identify the context.React Native
Expand React Native code sample
Expand React Native code sample
identify method tells the client to change the current context and obtain the feature flag values for the new context.ReactNativeLDClient. You must call identify before you can evaluate a feature flag for a specific context. End users will receive fallback values until you specify a context by calling identify.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.Here’s how:sheddable identify option to true. The timeout identify option defaults to five seconds. If the timeout expires, the promise that identify returns is rejected, but the SDK continues to identify the context.To learn more, read identify.Roku
Expand Roku code sample
Expand Roku code sample
identify() method tells the client to change the current context and obtain the feature flag values for the new context.To do this:Vue
Expand Vue code sample
Expand Vue code sample
useLDClient() and call the identify() method. The variation composables re-evaluate after identify() completes. Your components update without additional work.identify() returns a promise that resolves to a result object, and the promise is never rejected. The result’s status is completed, error, timeout, or shed. By default, identify calls are sheddable. If you call identify() again before an earlier call completes, the SDK discards the intermediate calls and identifies only the most recent context. To queue identify calls and complete them in order instead, set the sheddable identify option to false.To react to context changes elsewhere in your application, call onContextChange() on the client. It returns a function that unsubscribes the callback.Here’s how to identify a new context:onContextChange():Server-side SDKs
This feature is available in the following 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
Expand .NET (server-side) code sample
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:Identify.Apex
Expand Apex code sample
Expand Apex code sample
identify creates or updates users in LaunchDarkly, which makes them available for targeting and autocomplete on the Users list.To use identify:C++ (server-side)
Expand C++ (server-side) code sample
Expand C++ (server-side) code sample
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:Identify() in Client.Erlang
Expand Erlang code sample
Expand Erlang code sample
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.Go
Expand Go code sample
Expand Go code sample
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:Identify.Haskell
Expand Haskell code sample
Expand Haskell code sample
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.Java
Expand Java code sample
Expand Java code sample
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.Lua
Expand Lua code sample
Expand Lua code sample
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.Node.js (server-side)
Expand Node.js (server-side) code sample
Expand Node.js (server-side) code sample
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:identify.PHP
Expand PHP code sample
Expand PHP code sample
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:identify.Python
Expand Python code sample
Expand Python code sample
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:identify.Ruby
Expand Ruby code sample
Expand Ruby code sample
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:identify.Rust
Expand Rust code sample
Expand Rust code sample
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:identify.