Anonymous contexts - LaunchDarkly

This topic explains how to configure contexts as anonymous in LaunchDarkly SDKs. These features are available for all SDKs. Each SDK lets you designate anonymous contexts. Anonymous contexts don’t appear on your Contexts list, so you can’t search for them, and you can’t search for or autocomplete by their keys. If you use multi-contexts, you can choose to make only some contexts anonymous. To learn more, read Multi-contexts. In some client-side SDKs, if you don’t provide a key or set it to null, and set anonymous to true, then the SDK generates a random key for you. If you generate keys for anonymous contexts, session IDs or UUIDs work best. To learn more, read Anonymous contexts. Details about each SDK’s configuration are available in the SDK-specific sections below.

Client-side SDKs
Server-side SDKs
Edge SDKs
AI SDKs

Newer versions of LaunchDarkly SDKs replace users with contextsA 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.

Client-side SDKs

Here are the configuration options for anonymous 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
Vue: The Vue SDK relies on the JavaScript SDK for context-related functionality.

.NET (client-side)

Expand .NET (client-side) code sample

To distinguish logged-in end users from anonymous end users in the SDK:

Context context = Context.Builder("example-context-key")
    .Anonymous(true)
    .Build();

To auto-generate a key for any context whose anonymous attribute is true:

var config = Configuration
    .Builder("example-mobile-key", ConfigurationBuilder.AutoEnvAttributes.Enabled)
    .GenerateAnonymousKeys(true)
    .Build();

If you set this option, you must still specify a non-null key as a placeholder when you construct the Context, because the SDK does not allow a Context to exist with a null key. When you pass this context to SDK methods like Init or Identify, the SDK replaces the placeholder key with a generated key.In this example, the placeholder key is “placeholder-key”, but it could be any non-empty string:

Context context = Context.Builder("placeholder-key")
    .Anonymous(true)
    .Build();

Android

Expand Android code sample

To distinguish logged-in end users from anonymous end users in the SDK:

LDContext context = LDContext.builder("example-context-key")
    .anonymous(true)
    .build();

val context: LDContext = LDContext.builder("example-context-key")
    .anonymous(true)
    .build()

If you set this option, you must still specify a non-null key as a placeholder when you construct the LDContext, because this SDK does not allow a Context to exist with a null key. When you pass this context to SDK methods like Init or Identify, the SDK replaces the placeholder key with a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.

C++ (client-side)

Expand C++ (client-side) code sample

To distinguish logged-in end users from anonymous end users in the SDK:

auto context = ContextBuilder()
  .Kind("user", "example-user-key")
  .Anonymous(true)
  .Build();

LDContextBuilder builder = LDContextBuilder_New();

LDContextBuilder_AddKind(builder, "user", "example-user-key");
LDContextBuilder_Attributes_SetAnonymous(builder, "user", true);

LDContext context = LDContextBuilder_Build(builder);

To learn more, read ContextBuilder.

Electron

Expand Electron code sample

To distinguish logged-in end users from anonymous end users in the SDK:

const anonymousUser = { key: 'example-user-key', anonymous: true };

import * as LDElectron from 'launchdarkly-electron-client-sdk';

const anonymousUser: LDElectron.LDUser = { key: 'example-user-key', anonymous: true };

To create an anonymous user with an auto-generated key, specify the “anonymous” property and omit the “key” property. The LaunchDarkly client creates a unique key for this user and caches it locally:

const anonymousUser = { anonymous: true };

import * as LDElectron from 'launchdarkly-electron-client-sdk';

const anonymousUser: LDElectron.LDUser = { anonymous: true };

Flutter

Expand Flutter code sample

To distinguish logged-in end users from anonymous end users in the SDK:

final context = LDContextBuilder()
  .kind('user', 'example-user-key')
  .anonymous(true)
  .build();

LDContextBuilder builder = LDContextBuilder();
builder.kind('user', 'example-user-key')
    .anonymous(true);
LDContext context = builder.build();

To learn more, read anonymous.

iOS

Expand iOS code sample

To distinguish logged-in end users from anonymous end users in the SDK:

var contextBuilder = LDContextBuilder(key: "example-context-key")
contextBuilder.anonymous(true)

let context = try contextBuilder.build().get()

LDContextBuilder *builder = [[LDContextBuilder alloc] initWithKey:@"example-context-key"];
[builder trySetValueWithName:@"anonymous" value:[LDValue ofBool:true]];

LDContext *context = builder.build.success;

Alternatively, you can omit the key parameter. The client will automatically set the isAnonymous property for the context, and set the key to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.Here’s how:

// Have the SDK use a device persistent key.
// This sets `isAnonymous` by default.
let context = try LDContextBuilder().build().get()

// Have the SDK use a device persistent key.
// This sets `isAnonymous` by default.
LDContextBuilder *newThing = [[LDContextBuilder alloc] init];

JavaScript

Expand JavaScript code sample

To create an anonymous context, specify the anonymous property and omit the key property. The client will automatically set the key to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.Here’s how:

const anonymousUserContext = {
  kind: 'user',
  anonymous: true
};

// A multi-context can contain both anonymous and non-anonymous contexts.
// Here, the organization is not anonymous.
const multiContext = {
  kind: 'multi',
  user: anonymousUserContext,
  org: {
    key: 'example-organization-key',
    name: 'Acme, Inc.'
  }
}

import * as ld from 'launchdarkly-js-client-sdk';

const anonymousContext: ld.LDContext = {
  kind: 'user',
  anonymous: true
};

// A multi-context can contain both anonymous and non-anonymous contexts.
// Here, the organization is not anonymous.
const multiContext: ld.LDContext = {
  kind: 'multi',
  user: anonymousContext,
  org: {
    key: 'example-organization-key',
    name: 'Example organization name'
  }
}

Node.js (client-side)

Expand Node.js (client-side) code sample

To distinguish logged-in end users from anonymous end users in the SDK:

const anonymousContext = { kind: 'user', key: 'example-user-key', anonymous: true };

import * as ld from 'launchdarkly-node-client-sdk';

const anonymousContext: ld.LDContext = { kind: 'user', key: 'example-user-key', anonymous: true };

You can also have the SDK generate the key for you. Specify the anonymous property and omit the key property. The client will automatically set the key to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.Here’s how:

const anonymousContext = { kind: 'user', anonymous: true };

import * as ld from 'launchdarkly-node-client-sdk';

const anonymousContext: ld.LDContext = { kind: 'user', anonymous: true };

React Native

Expand React Native code sample

To create an create an anonymous context, specify the anonymous property and set the context key to an empty string.Here’s how:

// This device context is anonymous
const deviceContext = {
  // The key attribute is required and should be empty
  // The SDK will automatically generate a unique, stable key
  key: '',
  kind: 'device',
  deviceId: '12345',
  anonymous: true
}

// This user context is not anonymous
const userContext = {
  kind: 'user',
  key: 'example-user-key'
}

// The multi-context contains one anonymous context
// and one non-anonymous context
const multiContext = {
  kind: 'multi',
  user: userContext,
  device: deviceContext
}

In version 10 of the SDK, you must include the key attribute when building the anonymous context. If you set the key to an empty string, the client will automatically set the key to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots. We strongly recommend having the client manage the key for anonymous contexts. If you set the key to a non-empty string, the client uses that value as the key. However, the key may not be stable across restarts or reboots.The SDK gives a usage error if you omit the key attribute. It also gives a usage error if you set the key to an empty string and do not mark the context as anonymous.In versions 7 through 9 of the SDK, you may omit the context key when building an anonymous context, and the client will automatically set it to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.

Using a shared key between anonymous contexts in React Native for Android

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 some features will be limited or will not work as expected. To learn more, read Use a shared key between anonymous contexts.If you are using an older version of the React Native SDK on Android, there is some additional configuration required if you want to use a shared key between anonymous contexts.

Expand React Native v7.x-v9.x for Android code sample

If you do choose to use a shared key between anonymous contexts, and you:

have an Android application
are using the React Native SDK in versions 7.x through 9.x

then you must also explicitly configure the SDK to allow using a shared key between anonymous contexts. The generateAnonymousKeysAndroid configuration option defaults to true, which means that the SDK will automatically generate unique keys for anonymous contexts. If you need to use a shared key between anonymous contexts, then you must set this option to false.To learn more, read generateAnonymousKeys.The React Native SDK for iOS generates a context key for anonymous contexts only if you do not supply one. No additional SDK configuration is required if you are using a shared key for anonymous contexts with the React Native SDK for iOS.

React Web

All context-related functionality provided by the JavaScript SDK is also available in the React Web SDK.

Roku

Expand Roku code sample

To distinguish logged-in end users from anonymous end users in the SDK:

context = LaunchDarklyCreateContext({"key": "example-user-key", "kind": "user", "anonymous": true})

Vue

All context-related functionality provided by the JavaScript SDK SDK is also available in the Vue SDK.

Server-side SDKs

Here are the configuration options for anonymous 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

To distinguish logged-in end users from anonymous end users in the SDK:

var context = Context.Builder("example-context-key")
    .Anonymous(true)
    .Build();

Apex

Expand Apex code sample

To distinguish logged-in end users from anonymous end users in the SDK:

LDUser user = new LDUser.Builder('example-user-key')
    .setAnonymous(true)
    .build();

C++ (server-side)

Expand C++ (server-side) code sample

To distinguish logged-in end users from anonymous end users in the SDK:

auto context = ContextBuilder()
  .Kind("user", "example-user-key")
  .Anonymous(true)
  .Build();

LDContextBuilder builder = LDContextBuilder_New();

LDContextBuilder_AddKind(builder, "user", "example-user-key");
LDContextBuilder_Attributes_SetAnonymous(builder, "user", true);

LDContext context = LDContextBuilder_Build(builder);

To learn more, read ContextBuilder.

Erlang

Expand Erlang code sample

To distinguish logged-in end users from anonymous end users in the SDK:

    Context = ldclient_context:set(anonymous, true,
        ldclient_context:new(<<"example-user-key">>))

Go

Expand Go code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import (
    "github.com/launchdarkly/go-sdk-common/v3/ldcontext"
)

// Anonymous context with only a key
context1 := ldcontext.NewBuilder("example-context-key").Anonymous(true).Build()

// Anonymous context with a key plus other attributes
context2 := ldcontext.NewBuilder("context-key-456def").
    Anonymous(true).
    SetString("country", "Canada").
    Build()

Anonymous contexts do not appear on the Contexts list. Optionally, you can configure the SDK to omit data from anonymous contexts when sending related events to LaunchDarkly. Depending on how your application uses contexts, this can significantly decrease the amount of data your application sends to LaunchDarkly. To learn more, read EventsConfiguration.

Haskell

Expand Haskell code sample

To distinguish logged-in end users from anonymous end users in the SDK:

makeContext "example-user-key" "user"
  & withAnonymous True

Java

Expand Java code sample

To distinguish logged-in end users from anonymous end users in the SDK:

LDContext context = LDContext.builder("example-context-key")
  .anonymous(true)
  .build();

Lua

Expand Lua code sample

To distinguish logged-in end users from anonymous end users in the SDK:

-- to create an anonymous user context
local userContext = ld.makeContext({
    user = {
      key       = "example-user-key",
      anonymous = true
    }
})

-- to create an anonymous context of a different kind
local deviceContext = ld.makeContext({
    device    = {
      key       = "example-device-key",
      anonymous = true
    }
})

To learn more, read makeContext.

Node.js (server-side)

Expand Node.js (server-side) code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import * as ld from '@launchdarkly/node-server-sdk';

const context: ld.LDContext = {
  kind: 'user',
  key: 'example-user-key',
  anonymous: true,
}

PHP

Expand PHP code sample

To distinguish logged-in end users from anonymous end users in the SDK:

$context = LDContext::builder("example-context-key")->anonymous(true)->build();

Python

Expand Python code sample

To distinguish logged-in end users from anonymous end users in the SDK:

context = Context.builder("example-context-key").anonymous(True).build()

Ruby

Expand Ruby code sample

To distinguish logged-in end users from anonymous end users in the SDK:

context = LaunchDarkly::LDContext.create({ key: "example-context-key", anonymous: true })

Rust

Expand Rust code sample

To distinguish logged-in end users from anonymous end users in the SDK:

// Anonymous context with only a key
let context = ContextBuilder::new("example-context-key").anonymous(true).build();

// Anonymous context with a key plus other attributes
let context = ContextBuilder::new("example-context-key").
    anonymous(true).
    set_value("country", "US".into()).
    build();

Edge SDKs

Here are the configuration options for anonymous contexts in edge SDKs.

Akamai
Cloudflare
Fastly
Vercel

Akamai

Expand Akamai code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import type { LDContext } from '@launchdarkly/akamai-server-edgekv-sdk';

const anonymousContext: LDContext = { kind: 'user', key: 'example-user-key', anonymous: true };

Cloudflare

Expand Cloudflare code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import type { LDContext } from '@launchdarkly/cloudflare-server-sdk';

const anonymousContext: LDContext = { kind: 'user', key: 'example-user-key', anonymous: true };

Fastly

Expand Fastly code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import type { LDContext } from '@launchdarkly/fastly-server-sdk';

const anonymousContext: LDContext = { kind: 'user', key: 'example-user-key', anonymous: true };

Vercel

Expand Vercel code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import type { LDContext } from '@launchdarkly/vercel-server-sdk';

const anonymousContext: LDContext = { kind: 'user', key: 'example-user-key', anonymous: true };

AI SDKs

Here are the configuration options for anonymous contexts in AI SDKs.

.NET AI
Go AI
Node.js (server-side) AI
Python AI
Ruby AI

.NET AI

Expand .NET AI SDK code sample

To distinguish logged-in end users from anonymous end users in the SDK:

var context = Context.Builder("example-context-key")
    .Anonymous(true)
    .Build();

Go AI

Expand Go AI SDK code sample

To distinguish logged-in end users from anonymous end users in the SDK:

import (
    "github.com/launchdarkly/go-sdk-common/v3/ldcontext"
)

// Anonymous context with only a key
context1 := ldcontext.NewBuilder("example-context-key").Anonymous(true).Build()

// Anonymous context with a key plus other attributes
context2 := ldcontext.NewBuilder("context-key-456def").
    Anonymous(true).
    SetString("country", "Canada").
    Build()

Java AI

Expand Java AI SDK code sample

To distinguish logged-in end users from anonymous end users in the SDK:

LDContext context = LDContext.builder("example-context-key")
  .anonymous(true)
  .build();

Node.js (server-side) AI

Expand Node.js (server-side) AI SDK code sample

To distinguish logged-in end users from anonymous end users in the SDK:

const context: LDContext = {
  kind: 'user',
  key: 'example-user-key',
  anonymous: true,
}

const context = {
  kind: 'user',
  key: 'example-user-key',
  anonymous: true,
}

Anonymous contexts do not appear on the Contexts list.

Python AI

Expand Python AI SDK code sample

To distinguish logged-in end users from anonymous end users in the SDK:

context = Context.builder("example-context-key").anonymous(True).build()

Ruby AI

Expand Ruby AI SDK code sample

To distinguish logged-in end users from anonymous end users in the SDK:

context = LaunchDarkly::LDContext.create({ key: "example-context-key", anonymous: true })

​Client-side SDKs

​.NET (client-side)

​Android

​C++ (client-side)

​Electron

​Flutter

​iOS

​JavaScript

​Node.js (client-side)

​React Native

​Using a shared key between anonymous contexts in React Native for Android

​React Web

​Roku

​Vue

​Server-side SDKs

​.NET (server-side)

​Apex

​C++ (server-side)

​Erlang

​Go

​Haskell

​Java

​Lua

​Node.js (server-side)

​PHP

​Python

​Ruby

​Rust

​Edge SDKs

​Akamai

​Cloudflare

​Fastly

​Vercel

​AI SDKs

​.NET AI

​Go AI

​Java AI

​Node.js (server-side) AI

​Python AI

​Ruby AI

Client-side SDKs

.NET (client-side)

Android

C++ (client-side)

Electron

Flutter

iOS

JavaScript

Node.js (client-side)

React Native

Using a shared key between anonymous contexts in React Native for Android

React Web

Roku

Vue

Server-side SDKs

.NET (server-side)

Apex

C++ (server-side)

Erlang

Go

Haskell

Java

Lua

Node.js (server-side)

PHP

Python

Ruby

Rust

Edge SDKs

Akamai

Cloudflare

Fastly

Vercel

AI SDKs

.NET AI

Go AI

Java AI

Node.js (server-side) AI

Python AI

Ruby AI