evaluating.mdx

path	title	description	published	tags
/sdk/features/evaluating	Evaluating flags	This topic explains how to use the flag evaluation feature to serve different feature flag variations to users.	true	flag variation evaluation sdk boolvariation stringvariation jsonvariation

Overview

This topic explains how to use the flag evaluation feature to serve different feature flag variations to contexts and users. This feature is available for all of our 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 and segments.

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.

Configuring variations

Feature flag variations determine what a context or user receives when they encounter a feature flag. Every flag has at least two variations, one for when the flag is off, and one for when it's on. To learn more, read Creating flag variations.

This is an example of a flag with three variations:

Flags also have fallback values. The fallback value only returns if an error occurs. For example, the SDK serves the fallback value if LaunchDarkly is unreachable, the feature flag key doesn't exist, or the context or user doesn't have a key specified.

The flag evaluation feature adds a context to the Contexts lists, or user to the Users list, if one with the same key does not already exist. However, each SDK evaluates flags based only on the object you provide in the evaluation call.

Contexts without a context kind are interpreted as users

If you are working with an older version of the SDK, you may provide a user object in the evaluation call. If you are using an SDK that supports contexts, and don't supply the context kind, then that object is automatically interpreted as a context with a kind of "user." To learn more, read Understanding the foundations of contexts.

The SDK does not automatically use the attributes shown on the Contexts or Users list, and attributes are not synchronized across SDK instances. You must provide all relevant attributes for each evaluation for your targeting rules to apply correctly. To learn more, read User and context configuration.

You do not need to create contexts or users manually, but if you want to, you can with the identify feature. To learn more, read Identifying and changing contexts.

Details about each SDK's configuration are available in the SDK-specific sections below:

• Client-side SDKs
• Server-side SDKs
• Edge SDKs

Client-side SDKs

This feature is available for all of our client-side SDKs:

• .NET (client-side)
• Android
• C++ (client-side)
• Electron
• Flutter
• iOS
• JavaScript
• Node.js (client-side)
• React Native
• Roku

.NET (client-side)

The Variation method determines whether a flag is enabled or not for a specific context. In the client-side .NET SDK, there is a variation method for each type, such as BoolVariation or StringVariation.

variation calls take the feature flag key and a fallback value.

Here is an example:

client.BoolVariation("flag-key-123abc", false);

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Android

The variation method determines whether or not a flag is enabled for a specific context. variation calls take the feature flag key and a fallback value. When LDClient is initialized for the first time at app launch, contexts receive the feature flag fallback values until an initial connection to LaunchDarkly completes.

In Android, there is a variation method for each type, such as boolVariation or stringVariation.

Here is an example:

boolean variationResult = client.boolVariation(flagKey, false);

val variationResult: Boolean = client.boolVariation(flagKey, false)

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

C++ (client-side)

The variation methods determine whether or not a flag is enabled for a specific context. The variation method signatures take the feature flag key and a fallback value. When the client is initialized for the first time, contexts receive the feature flag fallback values until an initial connection to LaunchDarkly completes.

There are variation methods for each type, such as BoolVariation or StringVariation.

Here is an example:

bool show_feature = client.BoolVariation("flag-key-123abc", false);
if (show_feature) {
    // Application code to show the feature
} else {
    // The code to run if the feature is off
}

bool show_feature = LDClientSDK_BoolVariation(client, "flag-key-123abc", false);
if (show_feature) {
    // Application code to show the feature
} else {
    // The code to run if the feature is off
}

bool show_feature = LDBoolVariation(client, "flag-key-123abc", false);
if (show_feature) {
    // application code to show the feature
} else {
    // the code to run if the feature is off
}

bool show_feature = client->boolVariation("flag-key-123abc", false);

if (show_feature) {
    // application code to show the feature
} else {
    // the code to run if the feature is off
}

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

To learn more, read the Client documentation.

Electron

To evaluate any feature flag for the current user, call variation:

const flagValue = client.variation('flag-key-123abc', false);

// proceed based on flag value, for example:

if (flagValue)  {
  // feature flag is on
} else {
  // feature flag is off
}

const boolFlagValue = client.variation('bool-flag-key-123abc', false) as boolean;
const numberFlagValue = client.variation('number-flag-key-123abc', 2) as number;
const stringFlagValue = client.variation('string-flag-key-123abc', 'default') as string;

// proceed based on flag value, for example:

if (boolFlagValue)  {
  // feature flag is on
} else {
  // feature flag is off
}

You must provide all relevant user attributes for each evaluation for your targeting rules to apply correctly.

The return value of variation is always either one of the variations you defined for your flag in the flag's Targeting tab, or the fallback value. The fallback value is the second parameter to variation.

You can also fetch all flags for the current user.

Here is an example:

const flags = client.allFlags();
const flagValue = flags['flag-key-123abc'];

This returns a key-value map of all your feature flags. It contains null values for any flags that could not be evaluated.

Both of these methods are synchronous. The client always has the last known flag values in memory, so retrieving them does not involve any input/output (I/O).

Flutter

The variation methods determine the flag value for the current context. variation calls take the feature flag key and a fallback value. When LDClient is initialized for the first time at app launch, end users receive the feature flag fallback values until an initial connection to LaunchDarkly completes.

In Flutter, there is a variation method for each type, such as boolVariation or stringVariation.

Here is an example:

bool variationResult = await LDClient.boolVariation(flagKey, false);

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

iOS

The variation functions determine the flag value for the current context. Variation functions take the feature flag key and a fallback value as parameters. If the flag does not exist, cannot be cast to the correct return type, or the LDClient is not started, the function returns the fallback value.

In the iOS SDK, there is a variation method for each type, such as boolVariation or jsonVariation.

Here is an example:

let boolFlagValue = LDClient.get()!.boolVariation(forKey: "bool-flag-key-123abc", defaultValue: false)
let jsonFlagValue = LDClient.get()!.jsonVariation(forKey: "json-flag-key-456def", defaultValue: ["enabled": false, "special": "none"])

BOOL boolFlagValue = [[LDClient get] boolVariationForKey:@"bool-flag-key-123abc" defaultValue:NO];
LDValue* jsonFlagValue = [[LDClient get] jsonVariationForKey:@"json-flag-key-456def" defaultValue:[LDValue ofNull]];

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

JavaScript

The variation method determines which variation of a feature flag a context receives. variation calls take the feature flag key and a fallback value.

Here is an example of the variation method:

client.variation('flag-key-123abc', false);

const boolFlagValue = client.variation('bool-flag-key-123abc', false) as boolean;
const numberFlagValue = client.variation('numeric-flag-key-123abc', 2) as number;
const stringFlagValue = client.variation('string-flag-key-123abc', 'default') as string;

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Node.js (client-side)

The variation method determines which variation of a feature flag a user receives. variation calls take the feature flag key and a fallback value.

Here is an example:

const value = client.variation('flag-key-123abc', false);

const boolFlagValue = client.variation('flag-key-123abc', false) as boolean;
const numberFlagValue = client.variation('flag-key-123abc', 2) as number;
const stringFlagValue = client.variation('flag-key-123abc', 'default') as string;

You must provide all relevant user attributes for each evaluation for your targeting rules to apply correctly.

React Native

The variation method determines whether a flag is enabled or not for a specific context. In React Native, there is a variation method for each type, such as boolVariation or stringVariation.

Variation calls take the feature flag key and a fallback value. When LDClient is initialized for the first time at app launch, end users receive feature flag fallback values until an initial connection to LaunchDarkly is completed.

Here is an example:

let boolResult = await client.boolVariation('bool-flag-key-123abc', false);
let numResult = await client.numberVariation('numeric-flag-key-123abc', 2);
let stringResult = await client.stringVariation('string-flag-key-123abc', '');
let jsonResult = await client.jsonVariation('json-flag-key-123abc', {});

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Roku

The *variation methods determine which variation of a feature flag a context receives. *variation calls take a feature flag key and a fallback value.

Here is an example:

REM typed variations
myInt = launchDarkly.intVariation("flag-key-123abc", 123)

myBool = launchDarkly.boolVariation("flag-key-123abc", false)

myString = launchDarkly.stringVariation("flag-key-123abc", "hello world!")

myObjectOrArray = launchDarkly.jsonVariation("flag-key-123abc", {"value": 123})

REM generic variation
myValue = launchDarkly.variation("flag-key-123abc", false)

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Server-side SDKs

This feature is available for all of our server-side SDKs:

• .NET (server-side)
• Apex
• C/C++ (server-side)
• Erlang
• Go
• Haskell
• Java
• Lua
• Node.js (server-side)
• PHP
• Python
• Ruby
• Rust

.NET (server-side)

The Variation methods determine whether a flag is enabled or not for a specific context. In .NET, there is a Variation method for each type:

• BoolVariation
• DoubleVariation
• FloatVariation
• IntVariation
• JsonVariation
• StringVariation.

Variation calls take the feature flag key, a Context, and a fallback value.

Here is an example:

var value = client.BoolVariation("your.feature.key", context, false);

var value = client.BoolVariation("your.feature.key", user, false);

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Apex

The variation family of methods determine the flag value for a specific user. In Apex, there is a variation method for each type, such as boolVariation or stringVariation. The functions take an LDUser, feature flag key, and a fallback value.

Apex variation methods do not automatically add users to the Users list

Variation methods like boolVariation or stringVariation do not automatically generate index events due to limitations with the Apex platform. This means that the SDK does not automatically populate the Users list.

We recommend calling client.identify(user) with each of your users to generate user indexing events and populate your Users list. To learn more, read Identifying and changing contexts.

Here is an example:

Boolean value = client.boolVariation(user, 'your.feature.key', false);

You must provide all relevant user attributes for each evaluation for your targeting rules to apply correctly.

C/C++ (server-side)

The variation family of functions determine whether a flag is enabled or not for a specific user. In C, there is a variation function for each type, such as LDBoolVariation or LDStringVariation.

The functions take an LDClient, LDUser, feature flag key, fallback value, and optional LDDetails struct for an evaluation explanation.

Here is an example:

bool value = LDBoolVariation(client, user, "your.feature.key", false, NULL);

You must provide all relevant user attributes for each evaluation for your targeting rules to apply correctly.

Erlang

The variation function determines whether a flag is enabled or not for a specific context. The functions take a flag key, context, fallback value, and an instance tag. In the example below, the fallback value is false. The instance tag is optional.

Flag = ldclient:variation(<<"flag-key-123abc">>, #{key => <<"context-key-123abc">>,}, false, your_instance)

Flag = ldclient:variation(<<"flag-key-123abc">>, #{key => <<"user-key-123abc">>,}, false, your_instance)

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Go

The Variation methods determine whether a flag is enabled or not for a specific context. In Go, there is a Variation method for each type:

• BoolVariation
• IntVariation
• Float64Variation
• StringVariation
• JSONVariation, which can be any JSON type.

Variation methods take the feature flag key, a context, and a fallback value. In the example below, the fallback value is false.

The Variation call generates analytics events to tell LaunchDarkly about the flag evaluation and the context attributes, so the context will be added to the Contexts list if a context with that key doesn't exist already.

Here is an example:

result, _ := client.BoolVariation("your.feature.key", context, false)

// result is now true or false depending on the setting of this boolean feature flag

result, _ := client.BoolVariation("your.feature.key", user, false)

// result is now true or false depending on the setting of this boolean feature flag

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Haskell

The variation family of functions determine whether a flag is enabled or not for a specific context. In Haskell, there is a variation function for each type:

• boolVariation
• intVariation
• doubleVariation
• stringVariation
• jsonVariation

The functions take a Client, Context, feature flag key, and a fallback value. In the example below, the fallback value is False.

Here is an example:

myBoolVariation <- boolVariation client "flag-key-123abc" context False

myBoolVariation <- boolVariation client "flag-key-123abc" user False

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Java

The variation methods determine which variation of a feature flag a context receives.

In Java, there is a variation method for each type:

• boolVariation
• intVariation
• doubleVariation
• stringVariation
• jsonValueVariation, which can be of any JSON type.

The variation methods take the feature flag key, an LDContext, and a fallback value.

Here is an example:

boolean value = client.boolVariation("flag-key-123abc", context, false);

boolean value = client.boolVariation("your.feature.key", user, false);

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Lua

The variation family of functions determine whether a flag is enabled or not for a specific user. In Lua, there is a variation function for each type, such as boolVariation or stringVariation.

To learn more about configuration options, read the API docs.

Here is an example:

local value = client:boolVariation(user, "flag-key-123abc", false)

You must provide all relevant user attributes for each evaluation for your targeting rules to apply correctly.

Node.js (server-side)

The variation method determines which variation of a feature flag a context receives.

variation calls take the feature flag key, an LDContext, and a fallback value.

Here is an example:

client.variation('flag-key-123abc', context, false,
  (err, value) => {
    // check value and proceed accordingly
  });

client.variation('flag-key-123abc', user, false,
  (err, value) => {
    // check value and proceed accordingly
  });

You must provide all relevant attributes for each evaluation for your targeting rules to apply correctly.

PHP

The variation method determines which variation of a feature flag a context receives. variation calls take the feature flag key, an LDContext, and a fallback value.

Here is an example:

$value = $client->variation($key, $context, false);

$value = $client->variation($key, $user, false);

You must provide all relevant attributes for each evaluation for your targeting rules to apply correctly.

Python

The variation method determines which variation of a feature flag a context receives. variation calls take the feature flag key, a Context, and a fallback value.

Here is an example:

show_feature = ldclient.get().variation("your.feature.key", context, False)

show_feature = ldclient.get().variation("your.feature.key", user, False)

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Ruby

The variation method determines which variation of a feature flag a context receives.

variation calls take the feature flag key, an LDContext or user hash, and a fallback value. To learn more about constructing the context or user hash, read User and context configuration.

Here is an example:

value = client.variation("your.feature.key", context, false)

value = client.variation("your.feature.key", user, false)

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Rust

The variation methods determine whether a flag is enabled or not for a specific user. In Rust, there is a variation method for each type:

• bool_variation,
• int_variation,
• float_variation,
• str_variation for strings, and
• json_variation, which can be any JSON type.

variation methods take a Context, the feature flag key, and a fallback value. In the example below, the fallback value is false.

Here is an example:

let result = client.bool_variation(&context, "your.feature.key", false);
// result is now true or false depending on the setting of this boolean feature flag

let result = client.bool_variation(&user, "your.feature.key", false);
// result is now true or false depending on the setting of this boolean feature flag

You must provide all relevant context attributes for each evaluation for your targeting rules to apply correctly.

Edge SDKs

This feature is available for all of our edge SDKs:

• Akamai
• Cloudflare
• Vercel

Akamai

The variation method determines which variation of a feature flag a context receives. variation calls take the feature flag key, an LDContext, and a default value.

Here is an example:

const flagValue = await client.variation('flag-key-123abc', context, false);

You must provide all relevant attributes for each evaluation for your targeting rules to apply correctly.

Cloudflare

The variation method determines which variation of a feature flag a context receives. variation calls take the feature flag key, an LDContext, and a default value.

Here is an example:

const flagValue = await client.variation('flag-key-123abc', context, false);

You must provide all relevant attributes for each evaluation for your targeting rules to apply correctly.

Vercel

The variation method determines which variation of a feature flag a context receives. variation calls take the feature flag key, an LDContext, and a fallback value.

Here is an example:

const flagValue = await client.variation('flag-key-123abc', context, false);

You must provide all relevant attributes for each evaluation for your targeting rules to apply correctly.