GuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityLog In
Hey! These docs are for version 2.1, which is no longer officially supported. Click here for the latest version, 3.1!

Set Forced Variation

Forces a user into a variation for a given experiment for the lifetime of the Optimizely client.

The purpose of this method is to force a user into a specific variation or personalized experience for a given experiment. The forced variation value doesn't persist across application launches.

Version

SDK v2.1

Description

Forces a user into a variation for a given experiment for the lifetime of the Optimizely client. Any future calls to Activate, Is Feature Enabled, Get Feature Variable, and Track for the given user ID returns the forced variation.

Forced bucketing variations take precedence over whitelisted variations, variations saved in a User Profile Service (if one exists), and the normal bucketed variation. Impression and conversion events are still tracked when forced bucketing is enabled.

Variations are overwritten with each set method call. To clear the forced variations so that the normal bucketing flow can occur, pass null as the variation key parameter. To get the variation that has been forced, use Get Forced Variation.

This call will fail and return false if the experiment key is not in the project file or if the variation key is not in the experiment.

You can also use Set Forced Variation for feature tests.

Parameter definitions

This section provides general information about the required and optional parameters.
For the specific parameter name in one of Optimizely's supported languages, see Parameter names.

Parameter

Type

Description

experiment key
required

string

The key of the experiment to set with the forced variation.

user ID
required

string

The ID of the user to force into the variation.

variation key
optional

string

The key of the forced variation. Set the value to null to clear the existing experiment-to-variation mapping.

Parameter names

This section shows the specific parameter names for each supported language.

experimentKey
userId
variationKey
experimentKey
userId
variationKey
experimentKey
userId
variationKey
experimentKey
userId
variationKey
experimentKey
userId
variationKey
experimentKey
userId
variationKey
$experimentKey
$userId
$variationKey
experiment_key
user_id
variation_key
experiment_key
user_id
variation_key
experiment_key
user_id
variation_key

Returns

This section shows the specific return values for each supported language.

@return boolean `true` if the user was successfully forced into a variation, `false` if the `experimentKey` isn't in the project file or the `variationKey` isn't in the experiment.
<returns>A boolean value that indicates if the set completed successfully.</returns>
@return boolean `true` if the user was successfully forced into a variation, `false` if the `experimentKey` isn't in the project file or the `variationKey` isn't in the experiment.
@return boolean `true` if the user was successfully forced into a variation, `false` if the `experimentKey` isn't in the project file or the `variationKey` isn't in the experiment.
@return boolean A boolean value that indicates if the set completed successfully.
@return `YES` if the user was successfully forced into a variation, `NO` if the `experimentKey` isn't in the project file or the `variationKey` isn't in the experiment.
@return boolean A boolean value that indicates if the set completed successfully.
Returns:
    A boolean value that indicates if the set completed successfully.
@return [Boolean] `true` if the user was successfully forced into a variation, `false` if the `experimentKey` isn't in the project file or the `variationKey` isn't in the experiment.
@return A boolean value that indicates if the set completed successfully.

Examples

This section shows simple examples of how you can use the method.

optimizelyManager.getOptimizely().setForcedVariation("android_experiment_key", "1", "var_1")
var optlyObject = new Optimizely(TestData.Datafile, new ValidEventDispatcher(), LoggerMock.Object);
var actualVariation = optlyObject.GetVariation("android_experiment_key", "1", "var_1");
Optimizely optimizely = Optimizely.builder(validDatafile, mockEventHandler)
               .withBucketing(mockBucketer)
               .withConfig(validProjectConfig)
               .withErrorHandler(mockErrorHandler)
               .build();

optimizely.setForcedVariation(("android_experiment_key", "1", "var_1");
var didSetVariation = optlyInstance.setForcedVariation('testExperiment', 'testUser', 'control');
var didSetVariation = optlyInstance.setForcedVariation('testExperiment', 'user1', undefined);
NSString* experimentKey = @"testExperiment31";
[self.projectConfig setForcedVariation:experimentKey
                                   userId:@"user_a"
                             variationKey:@"variation"];
$optlyObject->setForcedVariation('test_experiment', 'test_user', 'test_variation')
result = optimizely_instance.set_forced_variation('test_experiment', 'test_user', 'control')
result = optimizely_instance.set_forced_variation('test_experiment', 'test_user', 'control')
[self.optimizely setForcedVariation:@”experimentKey1” userId:@”userID1” variationKey:@”variation1”];

Exceptions

None

See also

Get Forced Variation

Side effects

In the receiving client instance, sets the forced variation for the specified user in the specified experiment. This forced variation is used instead of the variation that Optimizely would normally determine for that user and experiment. See Use forced bucketing.

Source files

The table lists the language/platform source files containing the implementations.

Language/Platform

Source files

Android

OptimizelyClient.java

C#

Optimizely.cs

Java

Optimizely.java

JavaScript

index.js

Node

index.js

Objective-C and Swift

Optimizely.h

PHP

Optimizely.php

Python

optimizely.py

Ruby

optimizely.rb


Did this page help you?