abingo 1.1.0

data/.gitignore

@@ -0,0 +1 @@
+.svn

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in abingo.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,92 @@
+PATH
+  remote: .
+  specs:
+    abingo (1.1.0)
+      rails (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionmailer (3.2.9)
+      actionpack (= 3.2.9)
+      mail (~> 2.4.4)
+    actionpack (3.2.9)
+      activemodel (= 3.2.9)
+      activesupport (= 3.2.9)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.4)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.2.1)
+    activemodel (3.2.9)
+      activesupport (= 3.2.9)
+      builder (~> 3.0.0)
+    activerecord (3.2.9)
+      activemodel (= 3.2.9)
+      activesupport (= 3.2.9)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.9)
+      activemodel (= 3.2.9)
+      activesupport (= 3.2.9)
+    activesupport (3.2.9)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.1)
+    journey (1.0.4)
+    json (1.7.5)
+    mail (2.4.4)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.19)
+    multi_json (1.3.7)
+    polyglot (0.3.3)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (3.2.9)
+      actionmailer (= 3.2.9)
+      actionpack (= 3.2.9)
+      activerecord (= 3.2.9)
+      activeresource (= 3.2.9)
+      activesupport (= 3.2.9)
+      bundler (~> 1.0)
+      railties (= 3.2.9)
+    railties (3.2.9)
+      actionpack (= 3.2.9)
+      activesupport (= 3.2.9)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (>= 0.14.6, < 2.0)
+    rake (10.0.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    sprockets (2.2.1)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    thor (0.16.0)
+    tilt (1.3.3)
+    treetop (1.4.12)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.35)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  abingo!

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Patrick McKenzie
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,109 @@
+A/Bingo Version 1.0.3
+======
+
+Rails A/B testing.  One minute to install.  One line to set up a new A/B test.
+One line to track conversion.
+
+For usage notes, see: http://www.bingocardcreator.com/abingo
+
+Installation instructions are below usage examples.
+
+Key default features:
+  -- Conversions only tracked once per individual.
+  -- Conversions only tracked if individual saw test.
+  -- Same individual ALWAYS sees same alternative for same test.
+  -- Syntax sugar.  Specify alternatives as a range, array,
+       hash of alternative to weighting, or just let it default to true or false.
+  -- A simple z-test of statistical significance, with output so clear anyone in your organization
+       can understand it.
+
+Example: View
+
+<% ab_test("login_button", ["/images/button1.jpg", "/images/button2.jpg"]) do |button_file| %>
+  <%= img_tag(button_file, :alt => "Login!") %>
+<% end %>
+
+Example: Controller
+
+def register_new_user
+  #See what level of free points maximizes users' decision to buy replacement points.
+  @starter_points = ab_test("new_user_free_points", [100, 200, 300])
+end
+
+Example: Controller
+
+def registration
+  if (ab_test("send_welcome_email"), :conversion => "purchase")
+    #send the email, track to see if it later increases conversion to full version
+  end
+end
+
+Example: Conversion tracking (in a controller!)
+
+def buy_new_points
+  #some business logic
+  bingo!("buy_new_points")  #Either a conversion named with :conversion or a test name.
+end
+
+Example: Conversion tracking (in a view)
+
+Thanks for signing up, dude! <% bingo!("signup_page_redesign") >
+
+Example: Statistical Significance Testing
+
+Abingo::Experiment.last.describe_result_in_words
+=> "The best alternative you have is: [0], which had 130 conversions from 5000 participants (2.60%).
+    The other alternative was [1], which had 1800 conversions from 100000 participants (1.80%).
+    This difference is 99.9% likely to be statistically significant, which means you can be extremely
+    confident that it is the result of your alternatives actually mattering, rather than being due to
+    random chance.  However, this doesn't say anything about how much the first alternative is really
+    likely to be better by."
+
+Installation
+=======
+
+1)  REQUIRED: You'll need to generate a DB migration to prepare two tables, 
+then migrate your database.  (Note: slight edits required if you use the table names
+"experiments" or "alternatives" at present.)  Note: if you are upgrading to A/Bingo 1.0.0, you'll
+want to do this again.
+
+ruby script/generate abingo_migration
+rake db:migrate
+
+2)  REQUIRED: You need to tell A/Bingo a user's identity so that it knows who is
+who if they come back to a test.  (The same identity will ALWAYS see the same
+alternative for the same test.)  How you do this is up to you -- I suggest integrating
+with your login/account infrastructure.  The simplest thing that can possibly work
+
+#Somewhere in application.rb
+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
+
+3)  RECOMMENDED: A/Bingo makes HEAVY use of the cache to reduce load on the
+database and share potentially long-lived "temporary" data, such as what alternative
+a given visitor should be shown for a particular test.  You SHOULD use a cache
+which is shared across all Rails processes -- that probably means MemcachedStore or RedisStore.
+
+You PROBABLY SHOULD use a persistent cache in case you need to restart your
+machine.  This is an amazingly good use case for MemcacheDB, so if you want to
+try playing with that, Google it.  (Sets up VERY easily on the newer Ubuntu distros.)
+
+If you can't use a persistent cache, you're probably still OK if Memcached very
+rarely needs to be restarted.  If the cache gets flushed, you will double-count
+entrants to a particular experiment and possibly double-count conversions, but
+that may not be the worse thing in the world.
+
+A/Bingo defaults to using the same cache store as Rails.  If you want to change it
+
+#production.rb
+Abingo.cache = ActiveSupport::Cache::MemCacheStore.new("cache.example.com:12345") #best if really memcacheDB
+
+
+Copyright (c) 2009-2010 Patrick McKenzie, released under the MIT license

data/Rakefile

@@ -0,0 +1,24 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the abingo plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the abingo plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Abingo'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/abingo.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/abingo/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Glenn Gillen"]
+  gem.email         = ["me@glenngillen.com"]
+  gem.description   = %q{A split testing framework for Rails 3.x.x}
+  gem.summary       = %q{The ABingo split testing framework for Rails 3.x.x from Patrick McKenzie}
+  gem.homepage      = "https://github.com/glenngillen/abingo"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "abingo"
+  gem.require_paths = ["lib"]
+  gem.version       = Abingo::VERSION
+
+  gem.add_dependency "rails", "~> 3.0"
+end

data/generators/abingo_migration/abingo_migration_generator.rb

@@ -0,0 +1,24 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+class AbingoMigrationGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  source_root File.expand_path('../templates', __FILE__)
+
+  def self.next_migration_number(dirname) #:nodoc:
+    next_migration_number = current_migration_number(dirname) + 1
+    if ActiveRecord::Base.timestamped_migrations
+      [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % next_migration_number].max
+    else
+      "%.3d" % next_migration_number
+    end
+  end
+
+  def version
+    Abingo.MAJOR_VERSION.gsub(".", "")
+  end
+
+  def copy_migration
+    migration_template 'abingo_migration.rb', "db/migrate/abingo_migration#{version}"
+  end
+end

data/generators/abingo_migration/templates/abingo_migration.rb

@@ -0,0 +1,31 @@
+#Creates the two database tables, plus indexes, you'll need to use A/Bingo.
+
+class AbingoMigration<%= version -%> < ActiveRecord::Migration
+  def self.up
+    create_table "experiments", :force => true do |t|
+      t.string "test_name"
+      t.string "status"
+      t.timestamps
+    end
+
+    add_index "experiments", "test_name"
+    #add_index "experiments", "created_on"
+
+    create_table "alternatives", :force => true do |t|
+      t.integer :experiment_id
+      t.string :content
+      t.string :lookup, :limit => 32
+      t.integer :weight, :default => 1
+      t.integer :participants, :default => 0
+      t.integer :conversions, :default => 0
+    end
+
+    add_index "alternatives", "experiment_id"
+    add_index "alternatives", "lookup"  #Critical for speed, since we'll primarily be updating by that.
+  end
+
+  def self.down
+    drop_table :experiments
+    drop_table :alternatives
+  end
+end

data/lib/abingo.rb

@@ -0,0 +1,315 @@
+require "abingo/version"
+require "#{File.dirname(__FILE__)}/abingo_sugar"
+require "#{File.dirname(__FILE__)}/abingo_view_helper"
+require "abingo/controller/dashboard"
+require "abingo/rails/controller/dashboard"
+require "abingo/alternative"
+require "abingo/experiment"
+require "#{File.dirname(__FILE__)}/../generators/abingo_migration/abingo_migration_generator.rb"
+ActionController::Base.send :include, AbingoSugar
+ActionView::Base.send :include, AbingoViewHelper
+#This class is outside code's main interface into the ABingo A/B testing framework.
+#Unless you're fiddling with implementation details, it is the only one you need worry about.
+
+#Usage of ABingo, including practical hints, is covered at http://www.bingocardcreator.com/abingo
+
+class Abingo
+
+  @@VERSION = "1.1.0"
+  @@MAJOR_VERSION = "1.1"
+  cattr_reader :VERSION
+  cattr_reader :MAJOR_VERSION
+
+  #Not strictly necessary, but eh, as long as I'm here.
+  cattr_accessor :salt
+  @@salt = "Not really necessary."
+
+  @@options ||= {}
+  cattr_accessor :options
+
+  #Defined options:
+  # :enable_specification  => if true, allow params[test_name] to override the calculated value for a test.
+  # :enable_override_in_session => if true, allows session[test_name] to override the calculated value for a test.
+  # :expires_in => if not nil, passes expire_in to creation of per-user cache keys.  Useful for Redis, to prevent expired sessions
+  #               from running wild and consuming all of your memory.
+  # :count_humans_only => Count only participation and conversions from humans.  Humans can be identified by calling Abingo.mark_human!
+  #                       This can be done in e.g. Javascript code, which bots will typically not execute.  See FAQ for details.
+  # :expires_in_for_bots => if not nil, passes expire_in to creation of per-user cache keys, but only for bots.
+  #                         Only matters if :count_humans_only is on.
+
+  #ABingo stores whether a particular user has participated in a particular
+  #experiment yet, and if so whether they converted, in the cache.
+  #
+  #It is STRONGLY recommended that you use a MemcacheStore for this.
+  #If you'd like to persist this through a system restart or the like, you can
+  #look into memcachedb, which speaks the memcached protocol.  From the perspective
+  #of Rails it is just another MemcachedStore.
+  #
+  #You can overwrite Abingo's cache instance, if you would like it to not share
+  #your generic Rails cache.
+  cattr_writer :cache
+
+  def self.cache
+    @@cache || Rails.cache
+  end
+
+  #This method gives a unique identity to a user.  It can be absolutely anything
+  #you want, as long as it is consistent.
+  #
+  #We use the identity to determine, deterministically, which alternative a user sees.
+  #This means that if you use Abingo.identify_user on someone at login, they will
+  #always see the same alternative for a particular test which is past the login
+  #screen.  For details and usage notes, see the docs.
+  def self.identity=(new_identity)
+    @@identity = new_identity.to_s
+  end
+
+  def self.identity
+    @@identity ||= rand(10 ** 10).to_i.to_s
+  end
+
+  #A simple convenience method for doing an A/B test.  Returns true or false.
+  #If you pass it a block, it will bind the choice to the variable given to the block.
+  def self.flip(test_name)
+    if block_given?
+      yield(self.test(test_name, [true, false]))
+    else
+      self.test(test_name, [true, false])
+    end
+  end
+
+  #This is the meat of A/Bingo.
+  #options accepts
+  #  :multiple_participation (true or false)
+  #  :conversion  name of conversion to listen for  (alias: conversion_name)
+  def self.test(test_name, alternatives, options = {})
+
+    short_circuit = Abingo.cache.read("Abingo::Experiment::short_circuit(#{test_name})".gsub(" ", "_"))
+    unless short_circuit.nil?
+      return short_circuit  #Test has been stopped, pick canonical alternative.
+    end
+
+    unless Abingo::Experiment.exists?(test_name)
+      lock_key = "Abingo::lock_for_creation(#{test_name.gsub(" ", "_")})"
+      creation_required = true
+
+      #this prevents (most) repeated creations of experiments in high concurrency environments.
+      if Abingo.cache.exist?(lock_key)
+        creation_required = false
+        while Abingo.cache.exist?(lock_key)
+          sleep(0.1)
+        end
+        creation_required = Abingo::Experiment.exists?(test_name)
+      end
+
+      if creation_required
+        Abingo.cache.write(lock_key, 1, :expires_in => 5.seconds)
+        conversion_name = options[:conversion] || options[:conversion_name]
+        Abingo::Experiment.start_experiment!(test_name, self.parse_alternatives(alternatives), conversion_name)
+        Abingo.cache.delete(lock_key)
+      end
+    end
+
+    choice = self.find_alternative_for_user(test_name, alternatives)
+    participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+
+    #Set this user to participate in this experiment, and increment participants count.
+    if options[:multiple_participation] || !(participating_tests.include?(test_name))
+      unless participating_tests.include?(test_name)
+        participating_tests = participating_tests + [test_name]
+        expires_in = Abingo.expires_in
+        if expires_in
+          Abingo.cache.write("Abingo::participating_tests::#{Abingo.identity}", participating_tests, {:expires_in => expires_in})
+        else
+          Abingo.cache.write("Abingo::participating_tests::#{Abingo.identity}", participating_tests)
+        end
+      end
+      #If we're only counting known humans, then postpone scoring participation until after we know the user is human.
+      if (!@@options[:count_humans_only] || Abingo.is_human?)
+        Abingo::Alternative.score_participation(test_name)
+      end
+    end
+
+    if block_given?
+      yield(choice)
+    else
+      choice
+    end
+  end
+
+
+  #Scores conversions for tests.
+  #test_name_or_array supports three types of input:
+  #
+  #A conversion name: scores a conversion for any test the user is participating in which
+  #  is listening to the specified conversion.
+  #
+  #A test name: scores a conversion for the named test if the user is participating in it.
+  #
+  #An array of either of the above: for each element of the array, process as above.
+  #
+  #nil: score a conversion for every test the u
+  def Abingo.bingo!(name = nil, options = {})
+    if name.kind_of? Array
+      name.map do |single_test|
+        self.bingo!(single_test, options)
+      end
+    else
+      if name.nil?
+        #Score all participating tests
+        participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+        participating_tests.each do |participating_test|
+          self.bingo!(participating_test, options)
+        end
+      else #Could be a test name or conversion name.
+        conversion_name = name.gsub(" ", "_")
+        tests_listening_to_conversion = Abingo.cache.read("Abingo::tests_listening_to_conversion#{conversion_name}")
+        if tests_listening_to_conversion
+          if tests_listening_to_conversion.size > 1
+            tests_listening_to_conversion.map do |individual_test|
+              self.score_conversion!(individual_test.to_s)
+            end
+          elsif tests_listening_to_conversion.size == 1
+            test_name_str = tests_listening_to_conversion.first.to_s
+            self.score_conversion!(test_name_str)
+          end
+        else
+          #No tests listening for this conversion.  Assume it is just a test name.
+          test_name_str = name.to_s
+          self.score_conversion!(test_name_str)
+        end
+      end
+    end
+  end
+
+  def self.participating_tests(only_current = true)
+    identity = Abingo.identity
+    participating_tests = Abingo.cache.read("Abingo::participating_tests::#{identity}") || []
+    tests_and_alternatives = participating_tests.inject({}) do |acc, test_name|
+      alternatives_key = "Abingo::Experiment::#{test_name}::alternatives".gsub(" ","_")
+      alternatives = Abingo.cache.read(alternatives_key)
+      acc[test_name] = Abingo.find_alternative_for_user(test_name, alternatives)
+      acc
+    end
+    if (only_current)
+      tests_and_alternatives.reject! do |key, value|
+        self.cache.read("Abingo::Experiment::short_circuit(#{key})")
+      end
+    end
+    tests_and_alternatives
+  end
+
+  #Marks that this user is human.
+  def self.human!
+    Abingo.cache.fetch("Abingo::is_human(#{Abingo.identity})",  {:expires_in => Abingo.expires_in(true)}) do
+      #Now that we know the user is human, score participation for all their tests.  (Further participation will *not* be lazy evaluated.)
+
+      #Score all tests which have been deferred.
+      participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+
+      #Refresh cache expiry for this user to match that of known humans.
+      if (@@options[:expires_in_for_bots] && !participating_tests.blank?)
+        Abingo.cache.write("Abingo::participating_tests::#{Abingo.identity}", participating_tests, {:expires_in => Abingo.expires_in(true)})
+      end
+
+      participating_tests.each do |test_name|
+        Alternative.score_participation(test_name)
+        if conversions = Abingo.cache.read("Abingo::conversions(#{Abingo.identity},#{test_name}")
+          conversions.times { Alternative.score_conversion(test_name) }
+        end
+      end
+      true #Marks this user as human in the cache.
+    end
+  end
+
+  protected
+
+  def self.is_human?
+    !!Abingo.cache.read("Abingo::is_human(#{Abingo.identity})")
+  end
+
+  #For programmer convenience, we allow you to specify what the alternatives for
+  #an experiment are in a few ways.  Thus, we need to actually be able to handle
+  #all of them.  We fire this parser very infrequently (once per test, typically)
+  #so it can be as complicated as we want.
+  #   Integer => a number 1 through N
+  #   Range   => a number within the range
+  #   Array   => an element of the array.
+  #   Hash    => assumes a hash of something to int.  We pick one of the
+  #              somethings, weighted accorded to the ints provided.  e.g.
+  #              {:a => 2, :b => 3} produces :a 40% of the time, :b 60%.
+  #
+  #Alternatives are always represented internally as an array.
+  def self.parse_alternatives(alternatives)
+    if alternatives.kind_of? Array
+      return alternatives
+    elsif alternatives.kind_of? Integer
+      return (1..alternatives).to_a
+    elsif alternatives.kind_of? Range
+      return alternatives.to_a
+    elsif alternatives.kind_of? Hash
+      alternatives_array = []
+      alternatives.each do |key, value|
+        if value.kind_of? Integer
+          alternatives_array += [key] * value
+        else
+          raise "You gave a hash with #{key} => #{value} as an element.  The value must be an integral weight."
+        end
+      end
+      return alternatives_array
+    else
+      raise "I don't know how to turn [#{alternatives}] into an array of alternatives."
+    end
+  end
+
+  def self.retrieve_alternatives(test_name, alternatives)
+    cache_key = "Abingo::Experiment::#{test_name}::alternatives".gsub(" ","_")
+    alternative_array = self.cache.fetch(cache_key) do
+      self.parse_alternatives(alternatives)
+    end
+    alternative_array
+  end
+
+  def self.find_alternative_for_user(test_name, alternatives)
+    alternatives_array = retrieve_alternatives(test_name, alternatives)
+    alternatives_array[self.modulo_choice(test_name, alternatives_array.size)]
+  end
+
+  #Quickly determines what alternative to show a given user.  Given a test name
+  #and their identity, we hash them together (which, for MD5, provably introduces
+  #enough entropy that we don't care) otherwise
+  def self.modulo_choice(test_name, choices_count)
+    Digest::MD5.hexdigest(Abingo.salt.to_s + test_name + self.identity.to_s).to_i(16) % choices_count
+  end
+
+  def self.score_conversion!(test_name)
+    test_name.gsub!(" ", "_")
+    participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+    if options[:assume_participation] || participating_tests.include?(test_name)
+      cache_key = "Abingo::conversions(#{Abingo.identity},#{test_name}"
+      if options[:multiple_conversions] || !Abingo.cache.read(cache_key)
+        if !options[:count_humans_only] || Abingo.is_human?
+          Abingo::Alternative.score_conversion(test_name)
+        end
+
+        if Abingo.cache.exist?(cache_key)
+          Abingo.cache.increment(cache_key)
+        else
+          Abingo.cache.write(cache_key, 1)
+        end
+      end
+    end
+  end
+
+  def self.expires_in(known_human = false)
+    expires_in = nil
+    if (@@options[:expires_in])
+      expires_in = @@options[:expires_in]
+    end
+    if (@@options[:count_humans_only] && @@options[:expires_in_for_bots] && !(known_human || Abingo.is_human?))
+      expires_in = @@options[:expires_in_for_bots]
+    end
+    expires_in
+  end
+
+end