Kissable

Kissable is a gem used to create, track, and store information for A/B tests in user cookies.

Installation

Add this line to your application's Gemfile:

gem 'kissable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install kissable

Usage

Kissable helps you run A/B tests by breaking up your users into test groups (e.g. Original vs. Variant). Name your test, list your test groups, and the ratio at which people should be distributed to each group. Kissable does the assignment pseudo-randomly.

For anonymous users cookies must be enabled. Cookies are used to assign a user to a group and keep him there. For logged in users a unique identifier (e.g. login) is used instead for the same purpose.

You instantiate the object with these items.

Kissable::AB.new(testname, groups, ratio)

• testname (required) This should be unique per test. It both passes the property to KM tracking as well as helps generate unique user groups for the test.
• groups (optional) This is used to name the groups used in the test. It will accept up to four group names. Defaults to %w{Original Variant}.
• ratio (optional) The ratio of how you want users sent to the specified groups. It expects all weightings to equal 100. It defaults to an even weight for all groups in the test.
• Store the result from group and use it to set up a switch in the relevant controller.

# home_controller.rb
def index
  @ab_test = Kissable::AB.new('top-navigation test')
  @users_ab_group = @ab_test.group(cookies)

  case @users_ab_group
  when 'Original'
    render 'index'
  else
    render 'index-variant'
  end
end

• Inside of the individual template files, you can add KISSmetrics tracking code by passing the user's group into the #tracking_script instance method.

  ab_test = Kissable::AB.new('top-navigation test')
  users_ab_group = ab_test.group(cookies)
  ab_test.tracking_script(users_ab_group)

• For logged in users, you can use some unique identifier instead.

  ab_test = Kissable::AB.new('top-navigation test')
  users_ab_group = ab_test.group(email)
  # Add your custom tracking code here.

Rails

ab = Kissable::AB.new('some cool test')
ab.group(cookies)

Sinatra

Sinatra handles cookies much differently than Rails. Sinatra stores the cookies which were sent in the request object in request and the cookies which will be sent back to the user in the response object. In order to make this as easy as possible, Kissable uses a Sinatra cookie adapter. This adapter needs to be instantiated with the request and response objects, then passed to group.

sca = Kissable::SinatraCookieAdapter.new(request, response)

ab = Kissable::AB.new('some cool test')
users_ab_group = ab.group(sca)

Configuration

Kissable allows you some potential configurations.

Kissable.configure do |config|
  config.logger = Logger.new(STDOUT)
  config.domain = '.kissmetrics.com'
end

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request