bandit 0.0.7 → 0.0.8

data/README.rdoc

@@ -63,6 +63,21 @@ To see a dashboard with relevant information, go to:
 
     http://<yourhost>/bandit
 
+= User Tracking
+There are a few different ways that users/conversions can be tracked.  Instead of calling bandit_choose and bandit_convert! in your code, you may alternatively use one of the following method combinations:
+
+    bandit_simple_choose/bandit_simple_convert!   (no cookies involved, same as raw impressions)
+    bandit_session_choose/bandit_session_convert! (session cookie, same as bandit_choose with a fix)
+    bandit_sticky_choose/bandit_sticky_convert!   (persistent cookies)
+
+bandit_sticky_convert! creates a _converted cookie which stops additional conversions from being counted. For example, if you are collecting email addresses, a user may enter their email address more than once, but you may want to count all these attempts as one conversion.
+
+You may also use the bandit_sticky_choose/bandit_session_convert! combination if you wish to use persistent cookies but allow each user to convert multiple times. This way visitors are always presented with the same alternative until they convert, at which point they are presented with another and so on.
+
+Finally, if you use bandit_simple_convert!, please remember the second argument (alternative) is not optional, as we have no cookie to read from.
+
+The default bandit_choose/bandit_convert methods use the session based choose/convert.
+
 = Tests
 To run tests:
 

data/lib/bandit/experiment.rb

@@ -25,8 +25,8 @@ module Bandit
         alt = default
       else
         alt = Bandit.player.choose_alternative(self)
+        @storage.incr_participants(self, alt)
       end
-      @storage.incr_participants(self, alt)
       alt
     end
 

data/lib/bandit/extensions/controller_concerns.rb

@@ -3,32 +3,42 @@ require 'active_support/concern'
 module Bandit
   module ControllerConcerns
     extend ActiveSupport::Concern
-  
+
     module ClassMethods
-      
     end
 
     module InstanceMethods
+      # default convert is a session based conversion
       def bandit_convert!(exp, alt=nil, count=1)
+        bandit_session_convert!(exp, alt, count)
+      end
+
+      # look mum, no cookies
+      def bandit_simple_convert!(exp, alt, count=1)
+        Bandit.get_experiment(exp).convert!(alt, count)
+      end
+
+      # expects a session cookie, deletes it, will convert again
+      def bandit_session_convert!(exp, alt=nil, count=1)
         cookiename = "bandit_#{exp}".intern
+        cookiename_converted = "bandit_#{exp}_converted".intern
         alt ||= cookies.signed[cookiename]
-        unless alt.nil?
+        unless alt.nil? or cookies.signed[cookiename_converted]
           Bandit.get_experiment(exp).convert!(alt, count)
-          # delete cookie so we don't double track
           cookies.delete(cookiename)
         end
       end
 
-      def bandit_choose(exp)
-        name = "bandit_#{exp}".intern
-
-        # choose url param with preference
-        value = params[name].nil? ? cookies.signed[name] : params[name]
-
-        # choose with default, and set cookie
-        cookies.signed[name] = Bandit.get_experiment(exp).choose(value)
+      # creates a _converted cookie, prevents multiple conversions
+      def bandit_sticky_convert!(exp, alt=nil, count=1)
+        cookiename = "bandit_#{exp}".intern
+        cookiename_converted = "bandit_#{exp}_converted".intern
+        alt ||= cookies.signed[cookiename]
+        unless alt.nil? or cookies.signed[cookiename_converted]
+          cookies.permanent.signed[cookiename_converted] = "true"
+          Bandit.get_experiment(exp).convert!(alt, count)
+        end
       end
     end
-
   end
 end

data/lib/bandit/extensions/view_concerns.rb

@@ -3,22 +3,44 @@ require 'active_support/concern'
 module Bandit
   module ViewConcerns
     extend ActiveSupport::Concern
-  
+
     module ClassMethods
-      
     end
 
     module InstanceMethods
+      # default choose is a session based choice
       def bandit_choose(exp)
-        name = "bandit_#{exp}".intern
+        bandit_session_choose(exp)
+      end
 
+      # always choose something new and increase the participant count
+      def bandit_simple_choose(exp)
+        Bandit.get_experiment(exp).choose(nil)
+      end
+
+      # stick to one alternative for the entire browser session
+      def bandit_session_choose(exp)
+        name = "bandit_#{exp}".intern
         # choose url param with preference
         value = params[name].nil? ? cookies.signed[name] : params[name]
-
         # choose with default, and set cookie
         cookies.signed[name] = Bandit.get_experiment(exp).choose(value)
       end
-    end
 
+      # stick to one alternative until user deletes cookies or changes browser
+      def bandit_sticky_choose(exp)
+        name = "bandit_#{exp}".intern
+        # choose url param with preference
+        value = params[name].nil? ? cookies.signed[name] : params[name]
+        # sticky choice may outlast a given alternative
+        alternative = if Bandit.get_experiment(exp).alternatives.include?(value)
+                        value
+                      else
+                        Bandit.get_experiment(exp).choose(value)
+                      end
+        # re-set cookie
+        cookies.permanent.signed[name] = alternative
+      end
+    end
   end
 end

data/lib/bandit/version.rb

@@ -1,3 +1,3 @@
 module Bandit
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bandit
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 15
   prerelease: 
   segments: 
   - 0
   - 0
-  - 7
-  version: 0.0.7
+  - 8
+  version: 0.0.8
 platform: ruby
 authors: 
 - Brian Muller
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-05-09 00:00:00 Z
+date: 2012-05-10 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rails