• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Evaluating flags

Read time: 8 minutes
Last edited: Jun 18, 2021

Overview

This topic explains how to use the flag evaluation feature to serve different feature flag variations to users. This feature is available for all of our SDKs.

Configuring variations

Feature flag variations determine what a user sees 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.

Flags also have fallback variations. The fallback variation only returns if an error occurs. For example, LaunchDarkly serves the fallback variation if the feature flag key doesn't exist, or the user doesn't have a key specified.

The flag evaluation feature automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already. You do not need to create users manually, but if you want to, you can use the identify feature. To learn more, read Identifying and changing users.

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

  • Client-side SDKs
  • Server-side SDKs

Client-side SDKs

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

Android

The variation method determines whether or not a flag is enabled for a specific user. variation calls take the feature flag key and a fallback value. When LDClient is initialized for the first time at app launch, users 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's an example:

1boolean variationResult = ldClient.boolVariation(flagKey, false);

C/C++ (client-side)

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

There are variation methods for each type, such as LDBoolVariation / boolVariation or LDStringVariation / stringVariation.

1bool show_feature = LDBoolVariation(client, "YOUR_FLAG_KEY", false);
2if (show_feature) {
3 // application code to show the feature
4} else {
5 // the code to run if the feature is off
6}

Electron

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

1var showFeature = client.variation("YOUR_FEATURE_KEY", false);
2
3if (showFeature) {
4 // feature flag is on
5} else {
6 // feature flag is off
7}

The return value of variation is always either one of the variations you defined for your flag in the LaunchDarkly dashboard, or the default value. The default value is the second parameter to variation. It is what the client uses if it's not possible to evaluate the flag. For example, the default value returns if the flag key does not exist, or if something about the definition of the flag is invalid.

You can also fetch all flags for the current user.

Here's how:

1var flags = client.allFlags();
2var showFeature = flags['YOUR_FEATURE_KEY'];

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 user. variation calls take the feature flag key and a fallback value. When LDClient is initialized for the first time at app launch, 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.

For example:

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

iOS

The variation method returns the variation for the given feature flag. If the flag does not exist, cannot be cast to the correct return type, or the LDClient is not started, the method returns the default value. Use this method when the default value is a non-Optional type. LDFlagValue shows you all available types.

The LDClient must be started in order to return feature flag values. If the LDClient is not started, it always returns the default value. The LDClient must be online to keep the feature flag values up-to-date. When online, the LDClient has two modes for maintaining feature flag values: streaming and polling. The client app requests the mode by setting the config.streamingMode. Read LDConfig for details.

In streaming mode, the LDClient opens a long-running connection to LaunchDarkly's streaming server (called clientstream). When a flag value changes on the server, the clientstream notifies the SDK to update the value. Streaming mode is not available on watchOS. On iOS and tvOS, the client app must be running in the foreground to connect to clientstream. On macOS the client app may run in either foreground or background to connect to clientstream. If streaming mode is not available, the SDK reverts to polling mode.

In polling mode, the LDClient requests feature flags from LaunchDarkly's app server at regular intervals defined in the LDConfig. When a flag value changes on the server, the LDClient learns of the change the next time the SDK requests feature flags.

When offline, LDClient closes the clientstream connection and no longer requests feature flags. The LDClient returns feature flag values, assuming the LDClient was started, which may not match the values set on the LaunchDarkly server.

A call to variation records events reported later. Recorded events allow clients to analyze usage and assist in debugging issues. There is a single variation method for all types using Swift, but Objective-C requires type specific methods.

Here's an example:

1let boolFlagValue = LDClient.get()!.variation(forKey: "bool-flag-key", defaultValue: false)
2let dictionaryFlagValue = LDClient.get()!.variation(forKey: "dictionary-flag-key", defaultValue: ["a": 1, "b": 2] as [String: Any])

JavaScript

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

The default value is only be returned if an error is encountered, such as when the feature flag key doesn't exist or the user doesn't have a key specified.

Here is an example of the variation method:

1ldclient.variation("your.feature.key", false);

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 default value. The default value only returns if an error is encountered, such as if the feature flag key doesn't exist or the user doesn't have a key specified.

Here's an example:

1const value = ldClient.variation("your.feature.key", false);

React Native

The variation method determines whether a flag is enabled or not for a specific user. 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, users receive feature flag fallback values until an initial connection to LaunchDarkly is completed for the first time.

Here's an example:

1let jsonResult = await client.jsonVariation('MY_JSON_FLAG_KEY', {});

Roku

The *variation methods determine which variation of a feature flag a user receives.

*variation calls take a feature flag key and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

Here's an example:

1REM typed variations
2myInt = launchDarkly.intVariation("MY_FLAG_KEY", 123)
3
4myBool = launchDarkly.boolVariation("MY_FLAG_KEY", false)
5
6myString = launchDarkly.stringVariation("MY_FLAG_KEY", "hello world!")
7
8myObjectOrArray = launchDarkly.jsonVariation("MY_FLAG_KEY", {"value": 123})
9
10REM generic variation
11myValue = launchDarkly.variation("MY_FLAG_KEY", false)

Xamarin

The Variation method determines whether a flag is enabled or not for a specific user. In Xamarin, there is a variation method for each type, such as BoolVariation or StringVariation.

variation calls take the feature flag key and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

Here's an example:

1ldClient.BoolVariation("your.feature.key", false);

Server-side SDKs

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

.NET

The Variation methods determine whether a flag is enabled or not for a specific user. In .NET, there is a Variation method for each type, such as BoolVariation and StringVariation.

Variation calls take the feature flag key, a User, and a default value. The Variation call automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already.

Here's an example:

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

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 default value. The default value only returns if an error occurs. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

Here's an example:

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

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, default value, and optional LDDetails struct for an evaluation explanation (see below). The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

Here's an example:

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

Erlang

The variation function determines whether a flag is enabled or not for a specific user.

The functions take a flag key, user, default value and an instance tag. The instance tag is optional. The default variation only returns if an error occurs.

For example, if the feature flag key doesn't exist or the user doesn't have a key specified, the user sees the default variation value.

Flag = ldclient:variation(<<"my-bool-key">>, #{key => <<"aa0ceb">>,}, false, my_instance)

Go

The Variation methods determine whether a flag is enabled or not for a specific user. In Go, there is a Variation method for each type: BoolVariation, IntVariation, Float64Variation, StringVariation and JSONVariation, which can be any JSON type.

Variation methods take the feature flag key, a User, and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified. In the example above the default value is false.

The Variation call generates analytics events to tell LaunchDarkly about the flag evaluation and the user properties, so the user will be created in LaunchDarkly if a user with that key doesn't exist already.

Here's an example:

1result, _ := ldClient.BoolVariation("your.feature.key", user, false)
2
3// result is now true or false depending on the setting of this boolean feature flag

Haskell

The variation family of functions determine whether a flag is enabled or not for a specific user.

The functions take a Client, User, feature flag key, and a default value. The default value only returns if an error occurs. For example, if the feature flag key doesn't exist or the user doesn't have a key specified, the default value is returned.

Here's an example:

1myBoolVariation <- boolVariation client user "YOUR_FEATURE_KEY" False

Java

The variation methods determine which variation of a feature flag a user receives. In Java, there is a variation method for each type: boolVariation, intVariation, doubleVariation, stringVariation and jsonValueVariation, which can be of any JSON type.

The variation methods take the feature flag key, an LDUser, and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

The variation call automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already.

Here's an example:

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

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.

The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

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

Here's an example:

1local value = client:boolVariation(user, "YOUR_FEATURE_KEY", false)

Node.js (server-side)

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

variation calls take the feature flag key, an LDUser, and a default value. The default value only returns in offline mode or if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

The variation call automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already.

Here's an example:

1ldClient.variation("your.feature.key", user, false,
2 (err, show_feature) => {
3 if (show_feature) {
4 // application code to show the feature
5 }
6 else {
7 // the code to run if the feature is off
8 }
9 });

PHP

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

variation calls take the feature flag key, an LDUser, and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

The variation call automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already.

Here's an example:

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

Python

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

variation calls take the feature flag key, an LDUser, and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

The variation call automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already.

Here's an example:

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

Ruby

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

variation calls take the feature flag key, a user, and a default value. The default value only returns if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

The variation call automatically creates a user in LaunchDarkly if a user with that user key doesn't exist already.

Here's an example:

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