Traffic Distribution

Traffic distribution into the different test groups of the A/B test.

When conducting an A/B test, not only do you need to distribute your users to different test groups, you also need to write a logic for each test group. After the integration stages, the distribution of users into different test groups can be done through the Hackle SDK.

📘

Test Groups

The test groups are basically the different groups that are exposed to the versions (features, screens, algorithms, etc) of a page of an experiment. Test Groups include both the control test group A and treatment test groups B, C, D, etc., that are exposed to the "improved" versions of the pages.
The test groups can be set on the dashboard and further information on the test groups can be found on the What is a Test Group? document.

variation

Think of the variation as the term that is equivalent to different versions of the page being shown to users on your app or browser.
By passing the experiment key to the variation() method, you can distribute users and receive the result for the specific experiment. After that, we implement the logic of the page version applicable for each test group.

In the example code below, we are passing an experiment key of 42, and there are two test groups, A and B.

// Execution should occur after the SDK is ready. Don't forget to wrap with onReady.
hackleClient.onReady(function() {
  
  // Determines the test group to assign the user in an A/B tests with an experiment key of 42.
  // For undetermined cases, the user is returned to test group A. 
  const variation = hackleClient.variation(42);

  // Logic for the assigned test group.
  if (variation === "A") {
    // Logic for test group A
  } else if (variation === "B") {
    // Logic for test group B
  }
});

🚧

Notes on Using Custom Identifiers

Here are a few points to note that when using directly managed user identifier, and not the identifier provided by the client-side SDK.

Before performing the distribution, please make sure that the user object to be passed to the hackleClient.variation() method contains the user identifier value.
The role of the variation method is to distribute specific users into specific groups. Therefore, if there is no user identifier value, the distribution cannot be performed.

If you are not sure if it is implemented correctly, it is recommended to check the reason value by the method using the variation detail result variationDetail() method introduced below.

variationDetail

The variationDetail() method works the same as the variation() method but provides the reason for a user being distributed to a specific group. This method can be a useful tool to see if the distribution is working properly.
You must pass the experiment key as a parameter. For the example code below, we are passing experimental key 42.

hackleClient.onReady(function() {
  // Traffic distribution details 
  const decision = hackleClient.variationDetail(experimentKey);
  // Test group determined from distribution
  const variation = decision.variation;
  // Reason for distribution to a test group
  const reason = decision.reason;
});

You will receive the reason for the distribution or the allocation of a specific user to a specific test group in the form of SDK_NOT_READY. Please refer to the table below for the full list of different distribution reasons.

ReasonDescriptionDistribution Result
SDK_NOT_READYThe SDK is not ready to use.
(e.g. Initialization with the wrong SDK key)
(control) Test Group A
EXPERIMENT_NOT_FOUNDNo A/B tests were found for the experimental key you passed.
The experiment key may be incorrect or the experiment may be in archive status.
(control) Test Group A
EXPERIMENT_DRAFTThe A/B test has not yet been started (in draft mode).(control) Test Group A
EXPERIMENT_PAUSEDThe A/B test has been paused.(control) Test Group A
EXPERIMENT_COMPLETEDThe A/B test has ended.Final winning test group from the experiment
OVERRIDDENUsers are distributed to a specific test group by manual assignment.Manually assigned test group
TRAFFIC_NOT_ALLOCATEDThe A/B test is running, but user has not been assigned to the experiment.(control) Test Group A
TRAFFIC_ALLOCATEDUser has been assigned to a test group in the A/B test.Assigned test group
VARIATION_DROPPEDThe test group was removed from the A/B test.(control) Test Group A
INVALID_INPUTThe input value is not valid.
(e.g. A number was entered in a parameter that requires a character)
(control) Test Group A
EXCEPTIONAn unknown error has occurred.(control) Test Group A

Parameter

  • Parameter values of the distributed group can also be provided through the variationDetail() method.
  • Through the config object and the get() method, you can receive and use the parameter setting value set in the dashboard, and if you change the value in the A/B test parameter setting tab, the changed value is applied to the code.

📘

Parameter setting is only available for SDK version 11.3.0 or higher.

hackleClient.onReady(function() {
  
  const decision = hackleClient.variationDetail(experimentKey);
  
  // Get parameter value through get() method in traffic distribution details
  const parameterValue = decision.get("parameterKey", "defaultValue")

  // Get config information with full parameter setting values in traffic distribution decision details
  const config = decision.config

  // Same result value as decision.get() above
  const configParameterValue = config.get("parameterKey", "defaultValue")

  // Example of string type parameter value
  const strValue = decision.get("parmeterKey", "defaultValue")
  const strValueInConfig = config.get("parmeterKey", "defaultValue")

});
  • The parameterKey of the get() method is the key information set in A/B Test Parameter Settings and the defaultValue is the value returned when the distribution decision fails or when the wrong parameter type is entered.
  • In order to properly receive the information you set in the dashboard, you must enter a value corresponding to the parameter type of defaultValue you set in the dashboard.
  • JSON type is received in the form of a string, so in the case of JSON type, the defaultValue must be entered as a string type.
  • The parameter types supported by SDK are string, number, and boolean. JSON types set in the dashboard can be received in the form of String. The default value of the JSON type must be entered as a string type.