JavaScript Library - Running an A/B Test with KM.ab

Full Example
- Explaining KM.ab
- Notes
Weighted Variants

The Javascript API provides a function, KM.ab, to set up the majority of the A/B test. Specifically, it does three things:

Randomly assigns the current visitor to one of the variations passed in. (KM.ab returns the variation that was assigned, so you can save it as a JS variable.)
Ensures that subsequent calls to KM.ab returns the same variation for the visitor.
Sets a Kissmetrics property with the name of your experiment, and the value is the selected variant. In our example below, the A/B test will set the property “Signup Button Color” to either “red” or “green”. You will be able to segment any report using this property.

Full Example

Below shows an example of a complete A/B test, using KM.ab:

<!--
  Here is our signup button. Notice that it is hidden by
  setting the style to "display: none". Also notice that
  it is by default using the "green" image.
-->
<img src="/images/green.png" id="signup_button" style="display: none"/>

<script type="text/javascript">
  // If for some reason Kissmetrics doesn't load or there is an error we'll just show the default green button after 1.5s
  var abTimeout1 = setTimeout(function(){
    document.getElementById("signup_button").style.display = '';
  }, 1500);

  // Now we need to add some Javascript code to run our A/B test.
  // Using _kmq.push to call our setup function ensures that it is only called once KM is loaded.
  _kmq.push(function(){
    // Set up the experiment (this is the meat and potatoes)
    var color = KM.ab("Signup Button Color", ["red", "green"]);

    // Set the button color
    var button = document.getElementById("signup_button");
    button.src = "/images/"+color+".png"; // Set the button color
    button.style.display = ''; // Show the button

    // Clear the timeout, since this worked fine
    clearTimeout(abTimeout1);
  });

  // Record when someone clicks on the button
  _kmq.push(["trackClick", "signup_button", "Clicked Signup"])
</script>

Explaining KM.ab

Let’s take a closer look at what KM.ab() does:

var color = KM.ab("Signup Button Color", ["red", "green"]);

For each person seeing this A/B test, choose randomly between the available options “red” and “green”.
Sets a property “Signup Button Color” with the value “red” or “green”, depending on what was randomly chosen.

This is equivalent to:

// Only one of these is "executed":
_kmq.push(['set', {'Signup Button Color':'red'}]);   // option 1
_kmq.push(['set', {'Signup Button Color':'green'}]); // option 2

KM.ab() returns which variation is picked, to reuse as a JavaScript variable (color). To remember which variation was used, KM sets a cookie. Please look at our page on Developing Locally if you are testing KM.ab() locally.

Notes

Wrap the call to KM.ab() in a function that is pushed to _kmq, or you may encounter JS errors if our library has not completely loaded before this executes.
Our JavaScript library depends on cookies to work properly. Browsers do not preseve cookies from page to page in localhost, so please refer to our guide on developing locally.

Weighted Variants

When you use KM.ab() to set up a test, we’ll split the variations evenly by default. However, you can give the function an extra argument to indicate the distribution of the test. These are all valid options:

_kmq.push(function(){
  // Even weights, 50% red, 50% green (default)
  KM.ab("Button Color", ["red", "green"])

  // 70% red vs. 30% green
  KM.ab("Button Color", {"red":70, "green":30});

  // 70% red vs. 30% green, using decimals
  KM.ab("Button Color", {"red":0.7, "green":0.3});

  // 5:1 red vs. green
  KM.ab("Button Color", {"red":5, "green":1});


  // KM.ab works with more than just two alternatives
  // 33% red, 33% green, 33% blue
  KM.ab("Button Color", ["red", "green", "blue"])

  // 5:1:1 red vs. green vs. blue
  KM.ab("Button Color", {"red":5, "green":1, "blue":1})
})