No results for ""
  • Home
  • API docs


Anonymous contexts

Read time: 7 minutes
Last edited: May 01, 2024


This topic explains what anonymous contexts are, how their information is handled in LaunchDarkly, and how they contribute to your monthly account usage.

You can designate any context as an anonymous context. Anonymous contexts work just like other contexts, except that they don't appear on your Contexts list in LaunchDarkly. You can't search for anonymous contexts on your Contexts list, and you can't search or autocomplete by anonymous context keys. Anonymous contexts still count toward your limit for client-side monthly contexts or monthly active users (MAU).

Here is an example of an anonymous context:

"context" = {
"kind": 'user',
"anonymous": true,
"key": 'anon-user-key-123abc' // some SDKs will generate this for you

Designating anonymous contexts prevents unauthenticated users from diluting useful data on user contexts in the Contexts list. You can set the key attribute to a unique value for each context. Alternatively, some client-side SDKs can generate a unique, random value for each anonymous context and set the key attribute for you.

Configure your SDK: Anonymous contexts and users

Ensuring customer privacy

You can use anonymous contexts to hide personally identifiable information (PII), but we recommend using private attributes instead. To learn more, read Use private context attributes.

Consider using multi-contexts

On a sign-in page in a single-page app, you could represent the same person as an anonymous user before they log in, and a different user after they log in. You can initialize the client with an anonymous context with a context kind of "user." After the person logs in, you can update the user context so that it's no longer anonymous using your SDK's identify feature.

Alternatively, you could use a multi-context, that is, a set of several different contexts that you want to evaluate together. 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 information. To learn more, read Associate anonymous contexts with logged-in end users.

Context account limits

Your account is limited to 100,000,000 contexts by default. You may hit this limit accidentally if you use too many unique keys. If you feel like you hit this limit too frequently, you may be creating more contexts than you realize, including anonymous contexts.

Here are some examples of ways you may unintentionally create unique context keys:

  • By creating contexts that include request IDs. When you do this, each context generates a new context key every time it requests against the server. Contexts do not need a unique key to use a request ID. For example, an unauthenticated API might only give you a request ID, not a context key.
  • By creating contexts from server-to-server communication where there are no human operators, just software components interacting.
  • By using LaunchDarkly to configure log levels or tracing. When you do this, you may use a different type of ID, like a timestamp. LaunchDarkly classifies each of those IDs as unique IDs.

To learn how to delete a context instance, read Remove a context instance.

Manage anonymous contexts

LaunchDarkly identifies all contexts by their unique key, including anonymous contexts. Using unique keys for anonymous contexts allows you to observe anonymous traffic interacting with your application, target anonymous traffic with percentage rollouts, and use Experimentation.

Anonymous contexts can raise your MCI count, but there are actions you can take to manage your MCI when using anonymous contexts. To learn more about MCI, read Account usage metrics.

Store anonymous keys locally

If you provide the anonymous context key yourself, you must ensure that the context uses that same key on each subsequent visit to avoid inflating how many contexts you evaluate.

One strategy to make sure that you're using the same anonymous context key each time is to store the unique identifier in a cookie or local storage. Because this is such a common strategy, we've implemented it directly into many of our client-side SDKs. If you use a client-side SDK and want to use a unique key for your anonymous contexts, you can defer key generation onto the SDK. To do this, build a context object and omit the key completely. The SDK generates a unique identifier for the context and persists this unique identifier in local storage. Each subsequent context evaluation without a context key uses that saved unique identifier. Check your SDK's documentation to confirm whether it will generate a unique key for your anonymous contexts.

Configure your SDK: Anonymous contexts and users

A challenge from using cookies or local storage is that they are optional. End users can turn them off. They are also often not observed by bots and site crawlers.

Wait to initialize your SDK

If you don't need to expose flags to anonymous contexts, don't initialize the SDK client for anonymous contexts. Instead, wait to initialize the client until after you know who your audience is. To learn more about SDK client initialization, read the Getting started documentation for your SDK.

Use a shared key between anonymous contexts

Using a shared key prevents the use of some LaunchDarkly features

It is possible to use one, shared key between anonymous contexts. However, we do not recommend this. Using a shared key between anonymous contexts means that percentage rollouts, Experimentation, individual targeting, and other features will be limited or will not work as expected.

Click to expand details on using a shared key

To use a shared context key, set the key attribute to the same value for each of your anonymous contexts. Because the context key is the same, LaunchDarkly considers all of these anonymous contexts as a single context instance. Anonymous multi-contexts may count as more than one context.

However, using a shared key means that some LaunchDarkly features will not work as expected.

These features are affected when you use a shared key between anonymous contexts:

  • Individual targeting: You cannot individually target anonymous contexts if they share the same key. To learn more, read Individual targeting.
  • Percentage rollouts: If you are targeting anonymous contexts in percentage rollouts, you must assign variations by a unique attribute other than the key. Otherwise, all anonymous contexts will be served the same variation, and the feature may be rolled out to a much larger percentage of contexts than you intend. To learn more about variation assignments by attribute, read Understanding percentage rollout logic.
  • Experimentation: If you target anonymous contexts with a shared key within an experiment, a disproportionately large number of contexts will receive the same variation and your experiment results will be unreliable. To learn more about audience allocation for an experiment, read Allocating experiment audiences.

Associate anonymous contexts with logged-in end users

Before they log in, an end user might be represented by a device context. After they log in, they might be represented by two contexts, with one context kind based on their device and the second context kind based on their user information. This one person is now represented by two unique context keys.

If you want to associate two contexts with each other, you should identify a multi-context that includes both individual contexts when you want the association to occur. Unlike the aliasing method, the association doesn't persist between calls. You must send the contexts you want to associate in each variation or identify call and each track call.

Depending on your billing model, you may be billed by contexts, or by monthly active users (MAU). For contexts-based billing, only contexts of your primary context kind are counted toward your limit. For MAU-based billing, only user contexts are counted.

Anonymous users and aliasing

If you are not yet using an SDK version that supports contexts, you can associate an anonymous user with a specific, logged-in user using the alias method.

To learn more, read How to use contexts instead of alias.

Click to expand details on the deprecated alias method
This feature is not available in all SDKs

This section explains aliasing users, which is a deprecated feature for LaunchDarkly SDKs that have been updated to use contexts. For a list of SDKs that still support this feature, read Aliasing users.

In some cases, one person can be represented by multiple users in LaunchDarkly. If LaunchDarkly registers a person as an anonymous user, and that person later logs in to the application, LaunchDarkly registers them again as a logged-in user. This one person is now represented by two unique user keys. Both users are counted toward your MAU limit.

You can associate these two user keys by configuring your SDK to send alias events. Alias events connect two user keys and register them as one event-sending entity.

If you use Data Export or Experimentation, alias events are useful because they make the data represented in destinations and experiment results easier to understand. Alias events enable Data Export destinations to correlate the two user keys referring to the same underlying user. They also enable experiments to recognize when impressions and conversions occurred for a user, even if the user key changed between the two events.

To learn more about configuring your SDK to send alias events, read Aliasing users.

mParticle events require additional configuration

If you use mParticle as a Data Export destination, you must configure it to receive alias events in the LaunchDarkly UI. mParticle requires this additional configuration step to register events correctly.

To learn more, read mParticle.