Package Exports

pivot

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (pivot) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

pivot

pivot is a simple feature multi-variant and A/B testing framework for node and component.

It is designed to have a pluggable backend and provide a common interface to each testing strategy.

Installing

node

npm install --save pivot

component

component install CamShaft/pivot

Lookup Strategies

TODO

Assignment Strategies

TODO

Guide

Start by initializing pivot

/**
 * Module dependencies
 */
var pivot = require("pivot");

var experiments = pivot();

You'll need to tell it about the following methods:

lookup

This method looks up the variant settings in the backend. It is called any time pivot encounters a new feature.

experiments.lookup(function(name, variants, done){
  /**
   * We can do a few things here:
   *
   *   * Lookup our feature settings locally
   *   * If we dont have it, notify an admin control panel page
   *   * Log outdated features; either ones that should be integrated or ones that should be removed
   */

  var settings = []; // can come from anywhere: database, REST api, local json file, etc

  done(null, settings);
});

assign

This method takes the settings from the last call and assigns them to a user.

experiments.assign(function(name, settings, user, done){
  /**
   * If the variant is a group, we can inspect the `user` object to check where they fall
   * If the variant is a weight, we can implement our own random assignment algorithm
   *
   * The callback expects the name of the variant chosen for the given user
   */

  // For this example we're just going to assign the first variant to everyone
  done(null, settings[0]);
});

If you plan on using it paired with express/connect, you can also define the following. Otherwise, pivot will serialize/deserialize using the pivot cookie and req.user.

serialize

experiments.serialize(function(features, req, res, next){
  // Save the features for the user
  next();
});

deserialize

experiments.deserialize(function(req, res, next){
  // Retrieve the features for the request
  var features = {}; // can come from anywhere i.e. cookies, session, database
  next(null, features);
});

findUser

experiments.findUser(function(req, res, next){
  // Give the user for the request to pivot
  next(null, req.user);
});

feature

Once you have told pivot how to do things you can start adding features into the system:

// Variants, be default, are [false, true]
experiments.feature("my-cool-test");

// You can also add multi-variant
experiments.feature("my-other-test", ["blue", "red", "green"]);

variant

Now you can ask pivot to assign a variant to a user:

var user = {}; // pull from your user info

experiments.variant("my-cool-test", user, function(err, variant){
  // do something based on the value of variant
})

variant is either true or false depending on how we implemented the assign method.

handle

If you are using express/connect pivot comes with some batteries included:

/**
 * Module dependencies
 */
var express = require("express")
  , pivot = require("pivot");

/**
 * Create our server and experiments
 */
var app = module.exports = express()
  , experiments = pivot();

/**
 * Add our experiment setup to express
 */
app.use(experiments);

/**
 * Configure pivot here with the required methods
 */
...

experiments.feature("landing-page", ["minimal", "fancy"]);

app.get("/", function(req, res, next){
  var view = res.locals.features["landing-page"]; // either "minimal" or "fancy"
  res.render(view);
});

res.locals.features is now populated with all of the enabled features for the user.

Testing

npm install
npm test