auth0/auth0-ab

Name: auth0-ab

Owner: Auth0

Description: null

Created: 2015-08-26 15:17:54.0

Updated: 2018-03-21 20:08:57.0

Pushed: 2017-05-16 21:39:00.0

Homepage: null

Size: 2822

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

auth0-ab-testing

This library provides a module to execute A/B experiments on the client side. It was created to work together with auth0-metrics but is generic enough to work with any metrics library.

Installation

To install the dependencies, execute:

npm install

Usage (local)

To build and run the library locally, you can run npm run dev, that will let you include the library from http://localhost:9999/auth0-ab.js, there is an small demo to test the library in http://localhost:9999/

Usage (deploy)

CDN

Using our CDN is the preferred solution. Just add the following line in your project's HTML head and you are done.

ipt src="https://cdn.auth0.com/js/ab/1.0.3/auth0-ab.min.js"></script>

Examples

Basic set up

r experimentsDef = [
{
  name: 'experiment-1',
  variants: [
    {
      name: 'variant-1',
      settings: {
        // The 'weight' attribute is used to state the proportion of the
        // population that is going to go under this variant.
        // The higher weight value is, the higher is the probability
        // for an user of being chosen for the variant.
        weight: 0.5
      },
      properties: {
        title: 'Hello!',

        // JS Attribute - Explicit function definition (recomended)
        grettings: {
          type: 'js',
          fn: function(data) {
            alert("Hello " + data.name);
          }
        },

        // String function definition (util for server side provisioning)
        ask: {
          type: 'js',
          args: ['question'],
          body: 'return prompt(question);'
        }
      }
    },
    ...
  ]
},
...

Example 1

r ab = new Auth0AB({
experiments: experimentsDef
;

.start();

.onReady(function() {
var experiments = ab.getExperiments();

// Get one experiment
var experiment = experiments.findByName('experiment-1');

console.log(experiment.properties);
console.log(experiment.settings);

// Run all experiments
experiments.runAll();

// Run all experiments with names
experiments.runAll(['experiment-1', ...]);

// or run an expecific experiment
// Selects a variant from the experiment or returns current applicable variant (if any)
var variant = experiment.run();

// Set current variant on an specific experiment
experiment.setCurrentVariantByName('variant-1');

// Set current variant on a set of experiments
experiments.setCurrentVariantsByName({
  'experiment-1': 'variant-1',
  'experiment-2': 'variant-4',
  // ...
})

// Returns current applicable variant, null if none.
variant = experiment.getCurrentVariant();

// WARNING!: This JS will be run with the same privileges as any other JS in your
// website, it can access cookies, global variables, monkey patch code, etc.
// It is extremely important to make sure that you can trust the source of it
//
// Never execute JS from a source you cannot trust.
variant.getProperty('grettings').runInContext({ name: 'Damian' });

// Get plain object version of experiments / variants
experiments.toPlainObject()
experiment.toPlainObject()
variant.toPlainObject()
;

Example 2: Fetching experiments from an external source

r ab = new Auth0AB({
fetchFn: function() {
  // Returns a promise with the experiments
  // Expected result example:
  // [
  //   {
  //     name: 'experiment-1',
  //     variants: [
  //       {
  //         name: 'variant-1',
  //         settings: {
  //           // Weight is used to state the proportion of the population that is going to
  //           // go under this variant. The higher weight, the higher is the probability
  //           // for an user of being choosen for the variant.
  //           weight: 0.5
  //         },
  //         properties: {
  //           ...
  //         }
  //       },
  //       ...
  //     ]
  //   },
  //   ...
  // ];

  return $.get('/experiments');
}
;

.start();

.onReady(function(ab) {
var experiments = ab.getExperiments();
...
;

Example 3: Page.js Middleware

r ab = new Auth0AB({
experiments: experimentsDef
;
 or
 = new Auth0AB({
fetchFn: function() { // See example above }
;

.start();

ge('some/route', ab.integration('pagejs').middleware(/* optional */['experiment-1']), function(ctx, next) {
// Get variant
var variantExperiment1 = ctx.experiments.findByName('experiment-1').getCurrentVariant();

var html = template({
  title: variantExperiment1.getProperty('title').getValue(),
  somethingElse: ...
});

variantExperiment1.getProperty('js-property').runInContext('This is an argument!');

return container.render(html);
;