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.
Calling the Method
- // Activate the Full Stack A/B Test Experiment
- $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
- use Zoho\PageSense\PageSenseClient;
- // Create the user attributes array
- $userAttributes = [
- 'Browser' => 'Chrome',
- 'Device' => 'Desktop',
- 'OS' => 'Windows 10'
- ];
- // Activate the Full Stack A/B Test Experiment
- $variationName = $pageSenseClient->activateExperiment($experimentName, $userId, $userAttributes);
- // Define the logic for each variation
- if ($variationName === 'Original') {
- // CODE: Logic for handling the Original variation
- } elseif ($variationName === 'Variation 1') {
- // CODE: Logic for Variation 1
- } elseif ($variationName === 'Variation 2') {
- // CODE: Logic for Variation 2
- } elseif ($variationName === 'Variation 3') {
- // CODE: Logic for Variation 3
- } else {
- // 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
- //Activate experiment without user attributes
- $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.
Use 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.
Access your files securely from anywhere
Zoho CRM Training Programs
Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.
Zoho DataPrep Personalized Demo
If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.
- Zoho Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
Create. Review. Publish.
You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.
Zoho Sheet Resources
Zoho Forms Resources
Zoho Sign Resources
Sign, Paperless!
Zoho TeamInbox Resources
Design. Discuss. Deliver.
Related Articles
Activate Experiment
The ActivateExperiment API is used to activate a FullStack A/B Test experiment for a given user. It evaluates whether the user qualifies for the experiment and assigns a variation accordingly. Using ActivateExperiment with user attributes Method ...Activate Experiment
The activateExperiment API is used to activate a FullStack A/B Test experiment for a given user. It evaluates whether the user qualifies for the experiment and assigns a variation accordingly. Method String variationName = ...Get Variation Name
The Get Variation Name API is used to return the name of a FullStack A/B Test experiment. It evaluates whether the user qualifies for the experiment and assigns a variation accordingly. Using getVariationName without user attributes Method string ...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: String variationName = pageSenseClient.getVariationName(experimentName, userId, userAttributes); Parameters: ...Get Variation Name
The getVariationName() method retrieves the allocated variation name for a given user for a Full Stack A/B Test experiment. This API only provided the variation allocated for the user and does not trigger tracking events to PageSense. You can use ...