Documentation

Basics

This chapter documents the basics of Buncbbox.

Implementation

Bunchbox uses a JavaScript file on your website to do its work. Every account in Bunchbox has its own file. It contains the generic code that's the same for every account. And it also contains the information about experiments, variants, rules that is specific to the account.

The JavaScript file has two uses:

  1. Based on the active experiments and its variants Bunchbox decides if the current page is part of an experiment. If necessary a variant is applied to the current page.
  2. On the other hand it collects information about the current page and sends it to Bunchbox. This includes tracking conversions for active experiments if the goal conditions are met.
Code example

Bunchbox is added to the website with a regular scrip tag. For best performance this script tag needs to be added in a certain way:

  • It should be a synchronous tag. There the tag should not include the async attribute. It also should not be added via JavaScript (e.g. document.createElement("script");) because that implicitely loads the script asynchronously as well
  • It should be added as far up the document's HTML as possible, at the beginning of the <head> section if possible.
  • It is implemented protocol-free starting with //. This means it will always use the website's protocol, HTTP or HTTPS. It is always as secure as it needs to be.

A sample Bunchbox code looks like this: (Do not use this example)

<script src="//core.bunchbox.co/1352632f4ad7ed4458a43115.min.js"></script>
Attributes

Bunchbox can be supplied with additional information about the current visitor with attributes. These attribute can be used for targeting and goal conditions. Since Bunchbox executes its code immediately it is necessary to provide these attribute before the Bunchbox tag is loaded.

The following example demonstrates how attributes are supplied to Bunchbox:

<script>
    var _bb = _bb || [];
    _bb.push(["attribute", "gender", "m"]);
    _bb.push(["attribute", "vipMember", true]);
    _bb.push(["attribute", "orderSize", 99.95]);
    _bb.push(["attribute", "productIds", ["12345", "12344", "12345"]]);
</script>
<script src="//core.bunchbox.co/1352632f4ad7ed4458a43115.min.js"></script>

Attributes can be of one of four types:

  • Strings
  • Booleans
  • Numbers
  • String lists

Workflow

The JavaScript file is executed when a visitor opens a page in the browser. The following workflow describes the steps Bunchbox executes at that time:

Setup

First, all experiment data for the script's account is loaded and initialized.

Participation
  • Every experiment is checked to determine if it applies to the current page.
  • In case the page conditions are met a variant is determined. In case the visitor has been part of the experiment before he becomes part of the same variant as before. Otherwise a random variant is determined and stored in the cookie.
  • This information about the visitor being or becoming part of the experiment is sent to the Bunchbox server.
  • Afterwards, the variant is applied, either by executing its JavaScript or redirecting to the variant URL.
Conversion
  • Every experiment is checked again to determine if a goal's condition are met. If that is the case the conversion is tracked by sending information to the Bunchbox server.
  • If the goal is marked as the final goal of the experiment the information about the visitor's participation in this experiment is removed. The visitor can from now on start the experiment over again