Skip to content

First experiment: Change the design

Jump to bottom
Osvaldo edited this page Oct 1, 2023 · 10 revisions

After you have set up your site to do experiments with Abrantes, you can start your first experiment. This will help you to start understanding how Abrantes works.

In this first experiment we'll have a page with a header and a paragraph. We want to test what happens if we increase or decrease the text size. For this we'll create two variants: variant-1 with bigger text and variant-2 with smaller text.

The html and the css

First the html is:

<h1>Lorem ipsum</h1>

<p>Consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
    veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
    in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
    cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>

Now we'll add the css for the two variants to the page. As Abrantes will add a class name to the <body> tag identifying the variant, the CSS is:

<style>
    .MyDesginExp-1 h1 {
        font-size: 2.5rem;
    }

    .MyDesginExp-1 p {
        font-size: 1.5rem;
    }

    .MyDesginExp-2 h1 {
        font-size: 1.7rem;
    }

    .MyDesginExp-2 p {
        font-size: 0.8rem;
    }
</style>

Please note the CSS can be in a .css file linked inside the <head>. This makes a lot of sense for CSS that's being applied to many pages or for larger changes in CSS. CSS can become larger specially if you use media queries to experiment with specific design for certain screen sizes or types of device.

The JavaScript

Use JavaScript to control all about the experiment. Let’s go trough each line/block and explain it. Just like the css, JavaScript can be inserted in the html or in a separate .js file.

First we create an object to configure and control the experiment. It can be named anything you want, as long as it does not conflict with other objects in your page. In this example let's name it MyDesginExperiment

var MyDesginExperiment = Object.create(Abrantes);

Now we need to define how what each variant does. Each variant is defined by a JavaScript function in an array.

MyDesginExperiment.variants = [

    // Original
    function () {
    },

    // Variant 1
    function () {
    },

    // Variant 2
    function () {
    },

];

Please note that in this example all changes are defined only in the css, so all you need is an empty function for each variant, including the original.

Next we'll assign a variant to the user in this experiment. If the user was not engaged in this experiment a new random variant is assigned. If it was Abrantes will assign the same variant as before.

  • In the first parameter you'll create the experiment id, that should be unique for every experiment in your website. Repeating experiment ids may cause issues.
  • The second parameter is the traffic allocation and must be a number between 0 and 1. If it's 1, all users should be included in the experiment. If it's 0.5, half of the users should be included.
MyDesginExperiment.assignVariant("MyDesginExp", 1);

Next we'll render the variant with:

MyDesginExperiment.renderVariant();

In most cases you'll want to assign and render the variant as soon as possible, but not always. Abrantes gives you the control.

Almost always you'll want the user to see the same variant if it reloads the page or returns to the same page latter. Also if your conversion page is different from the test page, you'll want to persist the variant of the same experiment across pages. So you should add:

MyDesginExperiment.persist("session");

The line above persists the variant during a visit to the website. If you want to persist it when the user returns to the site latter, use userinstead of session.

Tracking user behavior

Finally you'll need to track user behavior to know which variant is the best. Abrantes uses Google Analytics 4 custom dimensions to record everything.

  1. Go to your Google Analytics 4 account
  2. Go to Admin
  3. Go to property > Custom definitions
  4. Click "Create custom dimensions"
  5. Fill the form as described bellow:
  • Dimension name: A short name about your experiment, for example "Font size experiment"
  • Scope: Event (important)
  • Description: A sentence to remind you about the experiment latter
  • Event parameter: A word, can use underscore. Take note of this, as you going to use it. let's use my_design_experiment

Add the tracking code to the experiment pages:

MyDesginExperiment.track("my_design_experiment");

See the code in the full example

Clone this wiki locally