Example code

import java.util.HashMap;

// Create the user attributes
HashMap<String, String> userAttributes = new HashMap<>();
userAttributes.put("Browser", "Chrome");
userAttributes.put("Device", "Desktop");
userAttributes.put("OS", "Windows 10");

// Activate the experiment
String variationName = pageSenseClient.activateExperiment(experimentName, userId, userAttributes);

// Define the behaviour for each variation
if ("Original".equals(variationName)) {
    // Code for 'Original'
} else if ("Variation 1".equals(variationName)) {
    // Code for 'Variation 1'
} else if ("Variation 2".equals(variationName)) {
    // Code for 'Variation 2'
} else if ("Variation 3".equals(variationName)) {
    // Code for 'Variation 3'
} else {
    // Code when the user is not part of the experiment
}

How the API works  

When the activateExperiment 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:

1. 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.

• If the user’s attributes match the audience targeting conditions, the API proceeds to the next step.

• 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.

2. 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.

• 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.

• If no stored variation exists, the API proceeds to allocate a new variation using the bucketing logic described below.

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

• 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.

• 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.

4. 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:

• "Original" variation is assigned a hash range from 0–2000

• "Variation 1" is assigned a hash range from 2001–4000

• "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:

• If it does, the corresponding variation is allocated to the user.

• 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.

5. Tracking and Analytics

Once a variation is successfully allocated, the API sends the corresponding tracking data to the PageSense server. This data is used for analytics, reporting, and experiment performance evaluation.

6. Return Value

• If the user qualifies for the experiment and a variation is successfully allocated, the API returns the name of the variation allocated.

• If the user fails to qualify for the experiment at any stage, the API returns null.

The activateExperiment 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.activateExperiment(experimentName, userId);

Parameter Details  

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.