Activate Experiment

Activate Experiment

The activateExperiment() method is used to activate a Full Stack A/B Test experiment for a given user. It evaluates whether the user qualifies for the experiment based on the audience targeting rules and assigns a corresponding variation if the user qualifies for the experiment.

This API helps you determine which variation of your experiment should be served for a specific user or session.

Calling the Method

  1. // Activate the Full Stack A/B Test Experiment
  2. $variationName = $pageSenseClient->activateExperiment($experimentName, $userId, $userAttributes);

Method Parameters

Parameter

Type

Description

experimentName

string

The name of the experiment to activate.

userId

string

A unique identifier for the user.

userAttributes

array

(Optional) Associative array of user attributes used for audience targeting and segmentation.


Return Value  

  • Returns the name of the allocated variation if the user qualifies for the Full Stack A/B Test.

  • Returns null if the user does not qualify for the experiment which can be due to the either user does not match the audience targeting rules for the experiment or the user falls outside the traffic allocated for the experiment.

Example Usage

  1. use Zoho\PageSense\PageSenseClient;
  2. // Create the user attributes array
  3. $userAttributes = [
  4.     'Browser' => 'Chrome',
  5.     'Device' => 'Desktop',
  6.     'OS' => 'Windows 10'
  7. ];
  8. // Activate the Full Stack A/B Test Experiment
  9. $variationName = $pageSenseClient->activateExperiment($experimentName, $userId, $userAttributes);
  10. // Define the logic for each variation
  11. if ($variationName === 'Original') {
  12.     // CODE: Logic for handling the Original variation
  13. } elseif ($variationName === 'Variation 1') {
  14.     // CODE: Logic for Variation 1
  15. } elseif ($variationName === 'Variation 2') {
  16.     // CODE: Logic for Variation 2
  17. } elseif ($variationName === 'Variation 3') {
  18.     // CODE: Logic for Variation 3
  19. } else {
  20.     // CODE: When user is not part of any variation}


How the API Works  

When activateExperiment() method is invoked, it follows a series of steps to determine whether a variation should be assigned to the user:

1. Audience Targeting  

The API first checks whether the user meets the experiment’s audience targeting rules defined in PageSense. These rules can include user attributes like browser, device type, OS, or any custom properties passed in the user attributes.

  • If the user’s attributes match the audience targeting conditions, the evaluation proceeds.

  • If they don’t match, the API immediately returns null, indicating the user is not eligible for the experiment.

2. User Storage Service  

User Storage Service stores the variation allocated to the users for a given experiment in the user provided storage layer such as Database, Redis Cache or File System. It ensures that the user is always assigned the same variation for a given A/B Test across different sessions and browsers.

  • If a stored variation already exists for the given user Id for the experiment, it is retrieved from the storage and returned.

  • If not, the SDK proceeds to assign a new variation via hashing algorithm.

3. Hashing with MurmurHash  

The user ID and the experiment key is combined to form a unique key and the API applies the MurmurHash algorithm to this unique key to produce a deterministic numeric value between 0 and 9999.

This hash value determines the user’s position in the experiment’s traffic allocation range and assign a variation.

  • MurmurHash always generates the same hash value for a given user  ID and  the experiment key combination.

  • This ensures that users always receive a consistent variation assignment across different sessions and browsers.

4. Variation Mapping  

Each variation within an experiment is assigned a value range based on its allocated traffic percentage. For example, in an A/B Test experiment with 80% traffic allocation and four variations, each variation being allocated individual traffic split of 25%, the value ranges for the four variations will be assigned as shown below,

Variation

Value Range

Original

0 – 2000

Variation 1

2001 – 4000

Variation 2

4001 – 6000

Variation 3

6001 – 8000

 

These ranges are non-overlapping and collectively cover the experiment’s total traffic allocation.

  • If the user’s hash value falls within a particular variation’s range, that variation will be allocated to the user.

  • If the user’s hash value falls outside all assigned ranges for the variations, no variation will be assigned to the user and the user will not qualify for the experiment, and NULL will be returned for the variation.

5. Tracking and Analytics  

Once a variation is assigned:

  • The API triggers the tracking events for the user visit to PageSense, recording the experiment name, user ID, variation name and user attribute details if passed.

6. Return Value

Outcome

Return Value

User qualifies and variation allocated

Returns the variation name

User does not match the audience targeting rules

Returns NULL

User falls outside traffic allocation

Returns NULL


Using activateExperiment() Without User Attributes  
You can also invoke the API without the user attributes parameter as shown below.

Calling the Method

  1. //Activate experiment without user attributes
  2. $variationName = $pageSenseClient->activateExperiment($experimentName, $userId);

How It Works  

  • Only Experiment Name and User Id are required.

  • Audience targeting is still evaluated. However:
    If the experiment targets “All Visitors”, the user qualifies for the experiment.
    If the experiment includes specific audience targeting condition, the user will not qualify for the experiment, since no user attributes are provided.

  • The API then applies the MurmurHash algorithm to determine the variation.

  • If the user’s hash value falls within a defined variation range of any variation, that matching variation is returned; otherwise, NULL is returned for the variation.

Best Practices  

  • Always use consistent, unique user IDs (e.g., Login ID, Email Address etc). Avoid using session IDs for the user IDs, as they change frequently resulting in different variation being served for the users for different sessions.

  • Always handle NULL returns gracefully. Add a fallback implementation in case the variation is returned as NULL.

  • Use caching for variation assignments for frequent users to avoid repeated hash evaluations.

NotesUse the same name for the keys in the User Attributes throughout your application to ensure consistency in audience targeting and report segmentation.

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.