Assign variations with bucketing IDs

🚧
BETA
Bucketing IDs are a beta feature intended to support customers who want to assign variations with a different identifier than they use to count visitors. For example, a company might want to assign variations by account ID while counting visitors by user ID. We're investigating the implications of bucketing IDs on results analysis, and we would love to have your feedback! If you want to participate in this beta release, please contact support.

By default, Optimizely assigns users to variations (in other words, Optimizely buckets users) based on submitted user IDs. You can change this behavior by including a bucketing ID.

With a bucketing ID, you decouple user bucketing from user identification. Users who have the same bucketing ID are put into the same bucket and are exposed to the same variation. The bucketing ID serves as the seed of the hash value used to assign the user to a variation. Users with the same bucketing ID share the same hash value, which is why they are exposed to the same variation. For more information, see How bucketing works in Full Stack.

Bucketing IDs are implemented as a reserved attribute that you can use when activating an experiment or evaluating a feature flag. The example shows how to include a bucketing ID—send the $opt_bucketing_id attribute in the attributes parameter of the Activate, Is Feature Enabled, Get Feature Variable, and Track methods.

import java.util.UUID;

import com.optimizely.ab.android.sdk.OptimizelyClient;
import com.optimizely.ab.config.Variation;

String experiementKey = "my_experiment";
// for simplicity sake, we are just using a generated user id
String userId = UUID.randomUUID().toString();

Map<String,String> attributes = new HashMap<String,String>();
attributes.put("ad_source", "my_campaign");
attributes.put("browser", "chrome");
// bucketing id can be passed in alone or with other attributes
attributes.put("$opt_bucketing_id", "bucketingId123");

// Activate with bucketing ID
Variation backgroundVariation = optimizely.activate(experiementKey, userId, attributes);

// Track with bucketing ID
// This tracks a conversion event for the event named `sample_conversion`
optimizely.track("sample_conversion", userId, attributes);

// GetVariation with bucketing ID
backgroundVariation = optimizely.getVariation(experimentKey, userId, attributes);

using OptimizelySDK;
using OptimizelySDK.Entity;

var optimizelyClient = new Optimizely(datafile);

var experimentKey = "my_experiment";
var userId = "user123";
UserAttributes attributes = new UserAttributes
{
  { "DEVICE", "iPhone" },
  { "AD_SOURCE", "my_campaign" },
  { "$opt_bucketing_id", "bucketingId123" }
};

// Activate with the bucketing ID
var variation = optimizelyClient.Activate(experimentKey, userId, attributes);

// Track with the bucketing ID
var eventKey = "my_conversion";
optimizelyClient.Track(eventKey, userId, attributes);

// Get variation with the bucketing ID
var variation2 = optimizelyClient.GetVariation(experimentKey, userId, attributes);

import java.util.UUID;

import com.optimizely.ab.Optimizely;
import com.optimizely.ab.config.Variation;

String experiementKey = "my_experiment";
// for simplicity sake, we are just using a generated user id
String userId = UUID.randomUUID().toString();

Map<String,String> attributes = new HashMap<String,String>();
attributes.put("ad_source", "my_campaign");
attributes.put("browser", "chrome");
// bucketing id can be passed in alone or with other attributes
attributes.put("$opt_bucketing_id", "bucketingId123");

// Activate with bucketing ID
Variation backgroundVariation = optimizelyClient.activate(experiementKey, userId, attributes);

// Track with bucketing ID
// This tracks a conversion event for the event named `sample_conversion`
optimizelyClient.track("sample_conversion", userId, attributes);

// GetVariation with bucketing ID
backgroundVariation = optimizelyClient.getVariation(experimentKey, userId, attributes);

var experimentKey = 'my_experiment';
var userId = 'user123';
var attributes = {
    'device': 'iphone',
    'ad_source': 'my_campaign',
    '$opt_bucketing_id': 'bucketingId123'
};

// Activate with the bucketing ID
var variationKey = optimizelyClient.activate(experimentKey, userId, attributes);

// Track with the bucketing ID
var eventkey = 'my_conversion';
optimizelyClient.track(eventKey, userId, attributes);

// Get variation with the bucketing ID
variationKey = optimizelyClient.getVariation(experimentKey, userId, attributes);

const bucketingIdAttributes = {
  device: "iphone",
  ad_source: "my_campaign",
  $opt_bucketing_id: "bucketingId123"
};

// Activate with the bucketing ID
var variationKey = optimizelyClient.activate(
  "my_experiment",
  userId,
  bucketingIdAttributes
);

// Track with the bucketing ID
var eventKey = "my_conversion";
optimizelyClient.track(eventKey, userId, bucketingIdAttributes);

// Get variation with the bucketing ID
variationKey = optimizelyClient.getVariation(
  "my_experiment",
  userId,
  bucketingIdAttributes
);

NSString *experimentKey = @"myExperiment";
NSString *userId = @"user123";
NSDictionary *attributes = @{@"device"              : @"iPhone",
                             @"ad_source"           : @"my_campaign",
                             @"$opt_bucketing_id"   : @"bucketingId123"};

// Activate with the bucketing ID
OPTLYVariation *variation = [optimizelyClient activate:experimentKey
                                                userId:user123
                                            attributes:attributes];

// Track with the bucketing ID
NSString *eventKey = @"myEvent";
[optimizelyClient track:eventKey
                        userId:userId
                    attributes:attributes];

// Get variation with the bucketing ID
OPTLYVariation *variation = [optimizelyClient activate:experimentKey
                                                userId:user123
                                            attributes:attributes];

$experimentKey = 'my_experiment';
$userId = 'user123';
$attributes = [
    'device' => 'iphone',
    'ad_source' => 'my_campaign',
    '$opt_bucketing_id' => 'bucketingId123'
];

// Activate with the bucketing ID
$variationKey = $optimizelyClient->activate($experimentKey, $userId, $attributes);

// Track with the bucketing ID
$eventKey = 'my_conversion';
$optimizelyClient->track($eventKey, $userId, $attributes);

// Get variation with the bucketing ID
$variationKey = $optimizelyClient->getVariation($experimentKey, $userId, $attributes);

experiment_key = 'my_experiment'
user_id = 'user123'
attributes = {
    'device': 'iphone',
    'ad_source': 'my_campaign',
    '$opt_bucketing_id': 'bucketingId123'
};

# Activate with the bucketing ID
variation_key = optimizely_client.activate(experiment_key, user_id, attributes)

# Track with the bucketing ID
event_key = 'my_conversion'
optimizely_client.track(event_key, user_id, attributes)

# Get variation with the bucketing ID
variation_key = optimizely_client.get_variation(experiment_key, user_id, attributes)

experiment_key = 'my_experiment'
user_id = 'user123'
attributes = {
    'device' => 'iphone',
    'ad_source' => 'my_campaign',
    '$opt_bucketing_id' => 'bucketingId123'
};

# Activate with the bucketing ID
variation_key = optimizely_client.activate(experiment_key, user_id, attributes)

# Track with the bucketing ID
event_key = 'my_conversion'
optimizely_client.track(event_key, user_id, attributes)

# Get variation with the bucketing ID
variation_key = optimizely_client.get_variation(experiment_key, user_id, attributes)

let experimentKey = "myExperiment"
let userId = "user123"
let forcedVariationKey = "treatment"
let attributes = ["device"           : "iPhone",
                  "ad_source"        : "my_campaign",
                  "$opt_bucketing_id": "bucketingId123"]

// Activate with the bucketing ID
let variation = optimizelyClient?.activate(experimentKey, userId, attributes)

// Track with the bucketing ID
let eventKey = 'myConversion'
optimizelyClient?.track(eventKey, userId, attributes)

// Get variation with the bucketing ID
variation = optimizelyClient?.getVariation(experimentKey, userId, attributes)

Using a bucketing ID does not affect the user ID. Event data submissions will continue to include user IDs. With the exception of assigning users to specific variations, features that rely on user IDs behave the same regardless of the presence of a separate bucketing ID. If you do not pass a bucketing ID to the attributes parameter, users are bucketed by user IDs, which is the default method.

📘
Notes

The bucketing ID is not persisted.

Bucketing IDs are only supported for feature tests and A/B tests, not rollouts.

Assign variations with bucketing IDs

🚧
BETA

📘
Notes

🚧BETA

📘Notes

🚧
BETA

📘
Notes