pivot
Version:
Simple feature, multi-variant and A/B testing
184 lines (137 loc) • 3.94 kB
Markdown
pivot [](https://travis-ci.org/CamShaft/pivot)
=====
_pivot_ is a simple feature multi-variant and A/B testing framework for [node](http://nodejs.org) and [component](http://component.io).
It is designed to have a pluggable backend and provide a common interface to each testing strategy.
Installing
----------
### node
```sh
npm install --save pivot
```
### component
```sh
component install CamShaft/pivot
```
Lookup Strategies
--------
TODO
Assignment Strategies
--------
TODO
Guide
-----
Start by initializing pivot
```js
/**
* 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.
```js
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.
```js
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
```js
experiments.serialize(function(features, req, res, next){
// Save the features for the user
next();
});
```
### deserialize
```js
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
```js
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:
```js
// 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:
```js
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:
```js
/**
* 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
-------
```js
npm install
npm test
```