Activate

Activates an A/B test for the specified user to start an experiment: determines whether they qualify for the experiment, buckets a qualified user into a variation, and sends an impression event to Optimizely.

This method takes into account any user attributes passed in, to determine if the user is part of the audience that qualifies for the experiment.

Version

SDK v2.1

Description

This method requires an experiment key, user ID, and (optionally) attributes. The experiment key must match the experiment key you created when you set up the experiment in the Optimizely app. The user ID string uniquely identifies the participant in the experiment. See Identify users for more information.

If the user qualifies for the experiment, the method returns the variation key that was chosen. If the user was not eligible—for example, because the experiment was not running in this environment or the user didn't match the targeting attributes and audience conditions—then the method returns null.

Activate respects the configuration of the experiment specified in the datafile. The method:

• Evaluates the user attributes for audience targeting.
• Hashes the user ID or bucketing ID to apply traffic allocation.
• Respects forced bucketing and whitelisting.
• Triggers an impression event if the user qualifies for the experiment.

Activate also respects customization of the SDK client. Throughout this process, this method:

• Logs its decisions via the logger.
• Triggers impressions via the event dispatcher.
• Raises errors via the error handler.
• Remembers variation assignments via the User Profile Service.
• Alerts notification listeners, as applicable.

📘

Note

For more information on how the variation is chosen, see How bucketing works in Full Stack.

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 names

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

experimentKey
userId
attributes

experimentKey
userId
userAttributes

experimentKey
userId
userAttribute

experimentKey
userId
attributes

experimentKey
userId
attributes

experimentKey
userId
attributes

experimentKey
userId
attributes

experiment_key
user_id
attributes

experiment_key
user_id
attributes

experimentKey
userId
attributes

Returns

The key of the variation where the user is bucketed, or null if the user doesn't qualify for the experiment.

The example shows the return as specified for each supported language.

@return The key of the variation where the user is bucketed, or `null` if the user doesn't qualify for the experiment.

<returns>null|Variation Representing variation</returns>

@return The key of the variation where the user is bucketed, or `null` if the user doesn't qualify for the experiment.

@return {string|null} variation key The key of the variation where the user is bucketed, or `null` if the user doesn't qualify for the experiment.

@return {string|null} variation key

@return The key of the variation where the user is bucketed, or `nil` if the user doesn't qualify for the experiment.

@return null|string Representing the variation key

Returns:
 Variation key representing the variation in which the user will be bucketed.
 None if user is not in experiment or if experiment is not running.

The key of the variation where the user is bucketed, or `nil` if the user doesn't qualify for the experiment.

@return The key of the variation where the user is bucketed, or `nil` if the user doesn't qualify for the experiment.

Examples

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

Variation v = optimizelyClient.Activate(“test_id”, “test_user_id”, Collections.singletonMap("house", "Gryffindor"));

var userAttributes = new UserAttributes
{
   {"device_type", "iPhone" },
   {"location", "San Francisco" }
};

var optlyObject = new Optimizely(TestData.Datafile, new ValidEventDispatcher(), LoggerMock.Object);
optlyObject.Activate("test_experiment", "test_user", userAttributes);

optimizely.activate(“test_experiment”, "user", Collections.singletonMap("browser_type", "firefox"))

var activate = optlyInstance.activate('testExperimentWithAudiences', 'testUser', {browser_type: 'firefox', 'test_null_attribute': null});

var activate = optlyInstance.activate('testExperimentWithAudiences', 'testUser', {browser_type: 'firefox', 'test_null_attribute': null});

optimizely?.activate("whiteListExperiment", userId: self.userId)

$optlyObject = new Optimizely(DATAFILE, new ValidEventDispatcher(), $this->loggerMock);
$userAttributes = [
   'device_type' => 'iPhone',
   'location' => 'San Francisco'
];

$optlyObject->activate('test_experiment', 'test_user', $userAttributes);

variation_key = optimizely_obj.activate('testExperimentWithFirefoxAudience', “user_01”, attributes={'browser_type': 'firefox'})

optly.activate('testExperimentWithFirefoxAudience', user_id, 'browser_type' => 'firefox')

let variation = self.optimizelyClient?.activate(self.experimentKey, userId:userId)

Exceptions

See also

Get Variation
Identify users
How bucketing works in Full Stack
Manage impressions

Side effects

The table lists other other Optimizely functionality that may be triggered by using this method.

Notes

Activate versus Get Variation

Use Activate when the visitor actually sees the experiment. Use Get Variation when you need to know which bucket a visitor is in before showing the visitor the experiment. Impressions are tracked by Is Feature Enabled when there is a feature test running on the feature and the visitor qualifies for that feature test.

For example, suppose you want your web server to show a visitor variation_1 but do not want the visitor to count until they open a feature that isn't visible when the variation loads, like a modal. In this case, use Get Variation in the backend to specify that your web server should respond with variation_1, and use Activate in the front end when the visitor sees the experiment.

Also, use Get Variation when you are trying to align your Optimizely results with client-side third-party analytics. In this case, use Get Variation to retrieve the variation and even show it to the visitor but only call Activate when the analytics call goes out.

See Manage impressions for more information about whether to use Activate or Get Variation for a call.

📘

Note

Conversion events can only be attributed to experiments with previously tracked impressions. Impressions are tracked by Activate, not by Get Variation. As a general rule, Optimizely impressions are required for experiment results and not only for billing.

Source files

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