Get Variation Name

Get Variation Name

The getVariationName API is used to get the allocated variation for the user for the specified  FullStack A/B Test experiment.

Method:

  1. String variationName = pageSenseClient.getVariationName(experimentName, userId, userAttributes);

Parameters:

Parameter

Type

Description

experimentName

String

The name of the experiment activated.

userId

String

A unique identifier for the user.

userAttributes

HashMap<String, String>

A map of user attributes used for audience targeting and segmentation.


Return Value:

  1. Returns the name of the allocated variation if the user qualifies for the FullStack A/B experiment.
  2. Returns null if the user does not meet the audience targeting criteria and fails to qualify for the FullStack A/B Experiment. 

Example code:

import java.util.HashMap;

// Create the User Attributes object

HashMap<String, String> userAttributes = new HashMap<>();

// Add the User Attribute values

userAttributes.put("Browser", "Chrome");
userAttributes.put("Device", "Desktop");
userAttributes.put("OS", "Windows 10");

// Activate the FullStack A/B Test Experiment 

String variationName = pageSenseClient.getVariationName(experimentName, userId, userAttributes);

// Define the Code Changes for each of the Variations of the FullStack A/B Test Experiment

if (variationName.equals("Original")){
// CODE: Write code for handling 'Original' }
else if (variationName.equals("Variation 1")){
// CODE: Write code for handling 'Variation 1' }
else if (variationName.equals("Variation 2")) {
// CODE: Write code for handling 'Variation 2' }
else if (variationName.equals("Variation 3")) {
// CODE: Write code for handling 'Variation 3' }
else{
// CODE: When user is not part of FullStack A/B Test Experiment. }

How this API Works:

When the getVariationName API is invoked, it follows a structured process to determine whether a variation should be allocated to the user. Below is a detailed breakdown of this process:

Audience Targeting

The API first evaluates whether the user qualifies for the experiment based on audience targeting conditions defined during experiment configuration.
These conditions are typically based on user attributes such as browser, device type, operating system, or any custom user data passed in the userAttributes.
  1. If the user’s attributes match the audience targeting conditions, the API proceeds to the next step.
  2. If the user does not meet these conditions, the API immediately returns null, indicating that the user is not eligible to be included in the experiment.

User Storage Service

Next, the API checks whether the User Storage Service is enabled. This service helps ensure consistency in variation assignments for the user by remembering previously assigned variations for users across multiple sessions.
  1. If a variation has already been assigned and stored for the user in the User Storage Service, the API retrieves and returns that stored variation.
  2. If no stored variation exists, the API proceeds to allocate a new variation using the bucketing logic described below.

Hashing with MurmurHash

The next step is to determine if the user qualifies for the experiment based on the experiment’s traffic allocation settings.

  1. The API applies the MurmurHash algorithm to the user's ID (userId). This hashing algorithm consistently generates a unique numeric value between 0 and 9999 for each user ID, which serves as the user's hash value.
  2. MurmurHash algorithm always generate the same hash value for the User ID for a given experiment across different sessions. This ensures deterministic and sticky variation assignment to the user for a given experiment.

Variation Mapping

Each variation within the experiment is assigned a specific range of hash values that corresponds to the variation’s allocated traffic percentage. 
For example:
  1. "Original" variation is assigned a hash range from 0–2000
  2. "Variation 1" is assigned a hash range from 2001–4000
  3. "Variation 2" is assigned a hash range from–6000 and so on.
These hash ranges are non-overlapping, ensuring a single variation is assigned per user and is Collectively exhaustive, covering the entire allocated traffic range of the experiment.

The API checks if the user’s hash value falls within any of these defined ranges:
  1. If it does, the corresponding variation is allocated to the user.
  2. If the hash value falls outside all assigned ranges, it means the user is not within the experiment’s traffic allocation, and null is returned.

Return Value

  1. If the user qualifies for the experiment and a variation is successfully allocated, the API returns the name of the variation allocated.
  2. If the user fails to qualify for the experiment at any stage, the API returns null.

Using getVariationName without user attributes

The getVariationName API may also be invoked without providing any user attributes. The following code demonstrates how to call the API without passing any user attribute parameters.

Method:

  1. String variationName = pageSenseClient.getVariationName(experimentName, userName);

Parameter Details

Parameter

Type

Description

experimentName

String

The name of the experiment activated.

userId

String

A unique identifier for the user.


How the API Works

  1. In this version of the API, only the experiment name and user ID are required.
  2. The audience targeting step is still executed; however, since no user attributes are provided, the user will qualify only for the experiments where the audience targeting criteria is configured as “All Visitors.”
  3. If the experiment includes any additional audience targeting conditions—such as device type, location, or custom attributes—the user will automatically fail the qualification check due to the absence of use attribute data for evaluation.
  4. For experiments that allow “All Visitors,” the standard MurmurHash-based variation allocation logic is applied. If the user's hash value falls within the defined range of any variation, that variation is allocated, and the API returns the name of the assigned variation.
  5. If the user's hash value falls outside all defined variation ranges—due to the experiment’s traffic allocation configuration—no variation is allocated, and the API returns null.
We hope this documentation helps make the process easy for you. Please feel free to reach out to us anytime by dropping an email to support@zohopagesense.com if you need more explanation or have any questions.