A/Bingo Installation Instructions

This is the quickstart version of these instructions. You'll find somewhat more detail in the README file included with the plugin. A/Bingo is designed to install in under five minutes.

1. Install the plugin:

   git clone git://git.bingocardcreator.com/abingo.git
       ---  or ---
   script/plugin install git://git.bingocardcreator.com/abingo.git
   

2. Create the required tables:

   ruby script/generate abingo_migration
   rake db:migrate
   

One of the key requirements for A/B testing is that users always see the same tests. Most A/B frameworks, such as Google Website Optimizer, track users via a cookie. This is a mediocre default chosen for convenience, which fails for common use cases such as presenting bob@example.com a consistent interface no matter whether he logs in from work, home, or an Internet cafe.

An identity can be any string. It should uniquely belong to a user and not change. A/Bingo doesn't care how you assign it.

Important technical note: A/Bingo breaks the MVC pattern to pass around the identity. This is a conscious decision made to simplify the A/Bingo API for end user programmers. An identity is shared across all concurrent requests handled by the Ruby interpreter.

If you are using Mongrel, your request is handled in a giant mutex. Accordingly, while you may feel unclean, A/Bingo is not a technical risk to you. If you are using a Ruby interpreter which can handle simultaneous requests in a single process, reimplement the passing of identities.

3. Assign the user a unique, long-lived identifying string (why):

   #in application.rb
   #This is sample code, the simplest that possibly works:
   before_filter :set_abingo_identity
   
   def set_abingo_identity
     if (session[:abingo_identity])
       Abingo.identity = session[:abingo_identity]
     else
       session[:abingo_identity] = Abingo.identity = rand(10 ** 10).to_i
     end
   end
   
   

4. Optional: Configure the cache, which should ideally be persistent (why). If you skip this, A/Bingo will use the Rails default cache. By default, Rails uses a MemoryStore cache in development and testing modes. Using this store with A/Bingo will cause A/Bingo to die with a "can't modify frozen array" exceptions when the user hits their second test if you are using Rails prior to version 2.3. This is due to a a bug in Rails which has subsequently been patched. Make sure you don't use the default MemoryStore cache!

   #production.rb
   #This is my memcacheDB instance
   Abingo.cache = ActiveSupport::Cache::MemCacheStore.new("cache.example.com:12345")
   

A/Bingo uses the cache for three purposes:

1. To keep tests loaded without hitting the DB.
2. To track whether a particular user has participated in an experiment yet.
3. To track whether a particular user has converted yet.

If your cache is flushed, then tests will be reloaded from the database (typically, only once, so this isn't too bad) and users could be double counted for participation in a test or for conversions. Accordingly, I recommend you use a persistent cache store: for most people, the best alternative is a MemcachedStore which is backed by a MemcacheDB instance.

5. Optional: Install the dashboard. This will let you quickly see the results of your tests, or end them, through a web interface.

   #Create a new controller.  The name is up to you -- this example
   #uses abingo_dashboard_controller.rb
   class AbingoDashboardController < ApplicationController
     #Declare any before_filters or similar which you need to use your authentication
     #for this controller.
   
     include Abingo::Controller::Dashboard
   end
   
   #You need to add the following to routes.rb:
     map.abingoTest "/abingo/:action/:id", :controller=> :abingo_dashboard
   
   #Now, simply navigate to http://www.example.com/abingo and you'll see your dashboard.
   #The templates can be customized to your liking in plugins/abingo/views.
   

• A/Bingo Home
• Get The Code
• Install (< 5 minutes)
• Getting Started Screencast
• Usage
• FAQ
• A/Bingo vs. Alternatives
• A/B Testing Resources & Acknowledgments

For added fun, you can see some real A/B test results I've collected from Bingo Card Creator, with commentary.

I've also written some A/B testing design documents, in case you want to write your own framework. Try it: it is fun, educational, and pays very well.