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 this API when you simply need to know which variation a user should be assigned and does not want to fire an activation event.
Calling the Method
- // Get the variation allocated to the user for a Full Stack A/B Test
- $variationName = $pageSenseClient->getVariationName($experimentName, $userId, $userAttributes);
Parameter | Type | Description |
experimentName | string | The name of the experiment to retrieve the variation for. |
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 meet the audience targeting criteria or falls outside the experiment’s traffic allocation.
Example Code
- use Zoho\PageSense\PageSenseClient;
- // Create the user attributes array
- $userAttributes = [
- 'Browser' => 'Chrome',
- 'Device' => 'Desktop',
- 'OS' => 'Windows 10'
- ];
- // Get the variation allocated to the user for the experiment
- $variationName = $pageSenseClient->getVariationName($experimentName, $userId, $userAttributes);
- // Handle variation-specific logic
- if ($variationName === 'Original') {
- // CODE: Logic for '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 getVariationName() method is invoked, it follows a series of steps to determine which variation should be assigned to the user.
1. Audience Targeting
The API first evaluates whether the user qualifies for the experiment based on audience targeting conditions defined in PageSense.
Targeting conditions typically include attributes like browser, device type, operating system, or any custom user data you pass in the user attributes.
If the user matches the targeting conditions → the process continues.
If the user does not match the targeting conditions → the variation will be returned as NULL.
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 and generate a numeric value between 0 and 9999.
MurmurHash algorithm generates the same hash value for a given user ID and experiment key pair. This ensures the user is always assigned a same variation for the given experiment across different sessions or browsers.
The generated hash value is then used to determine which variation the user falls into based on the experiment’s total traffic distribution and the individual traffic allocated for each variation.
4. Variation Mapping
Variation | Hash Value Range |
Original | 0 – 2000 |
Variation 1 | 2001 – 4000 |
Variation 2 | 4001 – 6000 |
Variation 3 | 6001 – 8000 |
If the user’s hash value falls within one of these ranges → that variation is returned.
If the user’s hash value falls outside all defined ranges → the user is not part of the experiment, and NULL will be returned.
5. Return Value Logic
Scenario | Return |
User qualifies and variation assigned | Variation name |
User fails audience targeting conditions | NULL |
User falls outside the traffic allocation | NULL |
Using getVariationName() Without User Attributes
The getVariationName() API can also be invoked without user attributes. Currently this type of API call can be used only for the experiments that target “All Visitors.” It cannot be used for experiments that have specific audience targeting conditions as all the users won't match the audience targeting conditions since the user attributes are not passed in this API call.
Calling the Method
- // Get the variation allocated to the user
- $variationName = $pageSenseClient->getVariationName($experimentName, $userId);
How It Works
Only ExperimentName and User Id are required.
Audience targeting still runs, but since no user attributes are passed:
The user will qualify only for the experiments that target “All Visitors.”
User will not qualify for the experiments that have specific audience targeting conditions because no user attributes are available.Once qualified, the API uses the MurmurHash-based bucketing to determine the variation assignment.
If the user’s hash value falls outside the experiment’s traffic allocation → returns NULL.
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 served for the user for different session.
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 across your application to ensure consistency in audience targeting and report segmentation.
Use getVariationName() API if you want only the variation to be rendered in your web pages; use activateExperiment() API when you also want to track an activation event.