express-split

Node.js Express middleware for split and AB testing. Allows to run multiple experiments and track conversions to choose the winning variant.

Usage

Add express-split to your project:

npm install express-split

Import express-split:

const split = require('express-split');

Add your experiments:

app.use(split({
  experiments: {
   'button-text': {options: ['sign-up', 'start', 'early-access']}
}}));

Start an experiment for a user (a random option will be assigned):

app.get('/', (req, res) => {
  req.split.set_id(1234); // Sets an indentifier for this user - can be avoided if using cookies
  req.split.start('button-text', () => {
    res.send('Home page');
  });
});

Do different things for each variant:

app.get('/product', (req, res) => {
  req.split.get('button-text', (option) => {
    if (option === 'start') {
      res.send('Start now!');
    } else if (option === 'start') {
      res.send('Get early access');
    } else {
      res.send('Sign up');
    }
  });
});

Mark convertions:

app.post('/subscribe', (req, res) => {
  req.split.finish('button-text', () => {
    res.send('Thanks!');
  });
});

Get the results for each experiment:

app.get('/admin/experiments', (req, res) => {
  req.split.results((results) => {
    res.send(JSON.stringify(results, null, 4));
  });
});

Get the results in a web GUI:

app.get('/admin/experiments', (req, res) => {
  req.split.gui(req, res);
});

Cookies

Note: If you don't use cookies you have to manually specify an integer identification for the user.

Call a cookie middleware like cookie-parser before using express-split:

const cookieParser = require('cookie-parser');
const split        = require('express-split');

app.use(cookieParser());
app.use(split({use_cookies: true}));

Options

| Option | Description | Default | | ----------------------|----------------|------------------------------------------------------------------------------------| | experiments | The available experiments and their options (see format below) | {} | | storage | Where to store the experiments results (Options: in-memory, mysql) | 'in-memory' | | db_pool | Connection pool object. Required if chosen a database storage | false | | db_table_experiments | Where to store the experiments in the database | 'split_experiments' | | db_table_users | Where to store the users in the database | 'split_users' | | use_cookies | Whether or not to use cookies. If false, use req.split.set_id() to manually set an identifier for each user | false | | cookie_name | The cookie name to use | '_splituid' | | cookie_max_age | The max-age to set for the cookie | 15552000000 (180 days) |

experiments

The experiments object holds the experiment name in each key, with the value of a new object options that holds an array of the variants for this experiment. As a convention, the first option should be the default option (if anything fails, the first option will be returned).

{
  'button-text': {
    options: ['sign-up', 'start', 'early-access']
  },
  'price': {
    options: ['300', '200', '400']
  }
}

Storage

in-memory (default)

Note: Using this option, your data will be deleted once the node process is stopped.

Stores the experiments and users data in the node process memory. Useful for setting up, not recommended in production.

mysql

Persists the data to a MySQL database. Creates 2 tables: split_experiments and split_users (configurable). A required db_pool object must be provided.

const app   = express();
const split = require('express-split');
const mysql = require('mysql');
const pool  = mysql.createPool({
  connectionLimit : 30,
  host     : 'localhost',
  user     : 'db_username',
  password : 'secret_password',
  database : 'db_name'
});

app.use(split({
  storage: 'mysql',
  db_pool: pool,
  experiments: {
    'price': {
      options: ['300', '200', '400']
    }
  }
}));

API

Constructor

set_id(user_id)

start(experiment_id, [callback])

get(experiment_id, callback)

finish(experiment_id, [callback])

results(callback)