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.

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  

• 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

1. // Get the variation allocated to the user
2. $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.

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.