sixpack / sixpack-js Goto Github PK

View Code? Open in Web Editor NEW

152.0 29.0 27.0 65 KB

Web browser & node.js client library for SeatGeek's Sixpack A/B testing framework

Home Page: http://sixpack.seatgeek.com/

License: Other

JavaScript 100.00%

sixpack-js's Introduction

sixpack-client

Node / browser client library for SeatGeek's Sixpack A/B testing framework.

Installation

Include the "sixpack.js" script. The sixpack object will be added to your environment. In the browser do the following:

<script src='sixpack.js'></script>

If you're using sixpack-client with node.js start by installing it with npm:

npm install sixpack-client

then require the "sixpack-client" module:

var sixpack = require('sixpack-client');

Usage

Check out the examples in the examples directory for some quick examples for how to use the library. Here's a very basic example in node:

var sixpack = require('sixpack-client');

var session = new sixpack.Session();
session.participate('test-exp', ['alt-one', 'alt-two'], function (err, res) {
  if (err) throw err;
  alt = res.alternative.name
  if (alt == 'alt-one') {
    console.log('default: ' + alt);
  } else {
    console.log(alt);
  }
});

When instantiating the session object you can pass optional params client_id, base_url, ip_address, user_agent

var sixpack = new sixpack.Session({
    client_id: 12345,
    base_url: 'http://google.com/sixpack',
    ip_address: '1.2.2.1',
    user_agent: 'ChromeBot'
});

Client ID is a previously generated client id that you've previously stored. IP Address and User Agent are used for bot detection.

Options

A number of options can be passed to a sixpack session. A few are highlighted below.

base_url. Base URL of the sixpack-server.
client_id. ID of the specific client.
ignore_alternates_warning. Allow sixpack-js to send a participate request which contains no alternates.
timeout. Number of milliseconds to wait for a response from sixpack-server before returning a timeout response.

Forcing an Alternative

For debugging / design work it can be useful to force a page to load using a specific alternative. To force an alternative use the force parameter to participate(). If you're using sixpack.js in the browser you can also just include a query parameter, e.g. /your-page?sixpack-force-EXPERIMENT_NAME=ALTERNATIVE_NAME.

Tests

A number of end-to-end tests are located in ./test/sixpack-test.js. They use mocha as the testing framework and chai as the assertion library, and require a running sixpack-server.

Run the tests with:

npm run test

Sixpack server location

The tests assume the sixpack-server server is running and located at http://localhost:5000. To use a different location, e.g. for a Docker container, run tests with the following pattern:

SIXPACK_BASE_URL=http://docker:5000 npm run test

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Write and run tests with npm test (see Tests above for more information)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push -u origin my-new-feature)
Create new pull request

sixpack-js's People

Contributors

Stargazers

Watchers

sixpack-js's Issues

Ask for window variable in order to determine if you are in the client side or server side.

Sixpack not handling non-500 errors

In certain cases, web servers can return 5XX errors that are not specifically 500. In our case, we're seeing 502 errors come through if the server becomes unavailable. With these errors, nginx servers return plain HTML documents.

Because sixpack checks strictly for 500 error codes, and then JSON parses the response body if status !== 500, 502 and 502 responses can cause an exception to be thrown, and the process thread to die.

The PR at #24 checks for all 5XX errors when receiving results, and try/catches the JSON parse, in case a non-son response is returned, making the library significantly more fault tolerant.

Missing version with new features

PR #19 was merged to master but no version was created nor released with this new feature!

npm version lags behind master

there have been significant changes since Aug 19, 2013 but the version on npm doesn't include any of the updates and doesn't match the documentation.

Can you please bump the package version so users can get the latest?

How does one get to the web ui to see the results?

Passing options to `sixpack.Session()` does not work in node v4

Stack is Node v4

var session = new sixpack.Session({client_id: req.user ? req.user._id : sixpack.generate_client_id(), base_url: 'http://XXX:8080'});

console.log(session)

{ client_id: { client_id: [Function], base_url: 'http://XXX:8080' },
  base_url: 'http://localhost:5000',
  ip_address: null,
  user_agent: null }

The options object seems to only be injected into client_id. I've tried just setting base_url too. This seems to work fine in the browser, with a quick jsfiddle here: http://jsfiddle.net/qpfac336/

ert

Force an experiment variation by passing a query string parameter

The client should parse a page's URL and show a particular experiment if it is specified as a query string parameter, e.g. http://example.com?experiment_1=var2.

Errors show up as timeouts

Because this project uses JSONP to receive HTTP responses, it can't receive any responses sent with HTTP 400/500 because the browser won't try to load them as actual scripts. To reproduce this, try converting a client ID that isn't a part of an experiment: you'll get a request timed out error because the callback is never executed, which is because the browser is not evaluating the response body that would look like sixpack.callback1({ "status": "failed", "message": "not in experiment" }) or something similar.

One way to fix this is to not use HTTP status codes and always return 200. Another solution is to avoid JSONP and use CORS and standard HTTP requests.