mikeg-vanity 1.3.0

data/lib/vanity/metric/google_analytics.rb

@@ -0,0 +1,70 @@
+module Vanity
+  class Metric
+    
+    # Use Google Analytics metric.
+    # 
+    # @example Page views
+    #   metric "Page views" do
+    #     google_analytics "UA-1828623-6"
+    #   end
+    # @example Visits
+    #   metric "Visits" do
+    #     google_analytics "UA-1828623-6", :visits
+    #   end
+    #
+    # @since 1.3.0
+    # @see Vanity::Metric::GoogleAnalytics
+    def google_analytics(web_property_id, *args)
+      gem "garb"
+      require "garb"
+      options = Hash === args.last ? args.pop : {}
+      metric = options.shift || :pageviews
+      @ga_resource = Vanity::Metric::GoogleAnalytics::Resource.new(web_property_id, metric)
+      @ga_mapper = options[:mapper] ||= lambda { |entry| entry.send(@ga_resource.metrics.elements.first).to_i }
+      extend GoogleAnalytics
+    rescue Gem::LoadError
+      fail LoadError, "Google Analytics metrics require Garb, please gem install garb first"
+    end
+
+    # Calling google_analytics method on a metric extends it with these modules,
+    # redefining the values and hook methods.
+    #
+    # @since 1.3.0
+    module GoogleAnalytics
+
+      # Returns values from GA using parameters specified by prior call to
+      # google_analytics.
+      def values(from, to)
+        data = @ga_resource.results(from, to).inject({}) do |hash,entry|
+          hash.merge(entry.date=>@ga_mapper.call(entry))
+        end
+        (from..to).map { |day| data[day.strftime('%Y%m%d')] || 0 }
+      end
+      
+      # Hooks not supported for GA metrics.
+      def hook
+        fail "Cannot use hooks with Google Analytics methods"
+      end
+
+      class Resource
+        include Garb::Resource
+
+        def initialize(web_property_id, metric)
+          @web_property_id = web_property_id
+          metrics metric
+          dimensions :date
+          sort :date
+        end
+
+        def results(start_date, end_date)
+          @profile = Garb::Profile.all.find { |p| p.web_property_id == @web_property_id }
+          @start_date = start_date
+          @end_date = end_date
+          Garb::ReportResponse.new(send_request_for_body).results
+        end
+
+      end
+
+    end
+  end
+end

data/lib/vanity/mock_redis.rb

@@ -0,0 +1,76 @@
+module Vanity
+  # The Redis you should never use in production.
+  class MockRedis
+    @@hash = {}
+
+    def initialize(options = {})
+    end
+
+    def [](key)
+      @@hash[key]
+    end
+
+    def []=(key, value)
+      @@hash[key] = value.to_s
+    end
+
+    def del(*keys)
+      keys.flatten.each do |key|
+        @@hash.delete key
+      end
+    end
+
+    def setnx(key, value)
+      @@hash[key] = value.to_s unless @@hash.has_key?(key)
+    end
+
+    def incr(key)
+      @@hash[key] = (@@hash[key].to_i + 1).to_s
+    end
+
+    def incrby(key, value)
+      @@hash[key] = (@@hash[key].to_i + value).to_s
+    end
+
+    def mget(keys)
+      @@hash.values_at(*keys)
+    end
+
+    def exists(key)
+      @@hash.has_key?(key)
+    end
+
+    def keys(pattern)
+      regexp = Regexp.new(pattern.split("*").map { |r| Regexp.escape(r) }.join(".*"))
+      @@hash.keys.select { |key| key =~ regexp }
+    end
+
+    def flushdb
+      @@hash.clear
+    end
+
+    def sismember(key, value)
+      case set = @@hash[key]
+      when nil ; false
+      when Set ; set.member?(value)
+      else fail "Not a set"
+      end
+    end
+
+    def sadd(key, value)
+      case set = @@hash[key]
+      when nil ; @@hash[key] = Set.new([value])
+      when Set ; set.add value
+      else fail "Not a set"
+      end
+    end
+
+    def scard(key)
+      case set = @@hash[key]
+      when nil ; 0
+      when Set ; set.size
+      else fail "Not a set"
+      end
+    end
+  end
+end

data/lib/vanity/playground.rb

@@ -0,0 +1,197 @@
+module Vanity
+
+  # Playground catalogs all your experiments, holds the Vanity configuration.
+  #
+  # @example
+  #   Vanity.playground.logger = my_logger
+  #   puts Vanity.playground.map(&:name)
+  class Playground
+
+    DEFAULTS = { :host=>"127.0.0.1", :port=>6379, :db=>0, :load_path=>"experiments" }
+
+    # Created new Playground. Unless you need to, use the global Vanity.playground.
+    def initialize(options = {})
+      @host, @port, @db, @load_path = DEFAULTS.merge(options).values_at(:host, :port, :db, :load_path)
+      @namespace = "vanity:#{Vanity::Version::MAJOR}"
+      @logger = options[:logger]
+      unless @logger
+        @logger = Logger.new(STDOUT)
+        @logger.level = Logger::ERROR
+      end
+      @redis = options[:redis]
+      @loading = []
+    end
+    
+    # Redis host name.  Default is 127.0.0.1
+    attr_accessor :host
+
+    # Redis port number.  Default is 6379.
+    attr_accessor :port
+
+    # Redis database number. Default is 0.
+    attr_accessor :db
+
+    # Redis database password.
+    attr_accessor :password
+
+    # Namespace for database keys.  Default is vanity:n, where n is the major release number, e.g. vanity:1 for 1.0.3.
+    attr_accessor :namespace
+
+    # Path to load experiment files from.
+    attr_accessor :load_path
+
+    # Logger.
+    attr_accessor :logger
+
+    # Defines a new experiment. Generally, do not call this directly,
+    # use one of the definition methods (ab_test, measure, etc).
+    #
+    # @see Vanity::Experiment
+    def define(name, type, options = {}, &block)
+      warn "Deprecated: if you need this functionality let's make a better API"
+      id = name.to_s.downcase.gsub(/\W/, "_").to_sym
+      raise "Experiment #{id} already defined once" if experiments[id]
+      klass = Experiment.const_get(type.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase })
+      experiment = klass.new(self, id, name, options)
+      experiment.instance_eval &block
+      experiment.save
+      experiments[id] = experiment
+    end
+
+    # Returns the experiment. You may not have guessed, but this method raises
+    # an exception if it cannot load the experiment's definition.
+    #
+    # @see Vanity::Experiment
+    def experiment(name)
+      id = name.to_s.downcase.gsub(/\W/, "_").to_sym
+      warn "Deprecated: pleae call experiment method with experiment identifier (a Ruby symbol)" unless id == name
+      experiments[id.to_sym] or raise NameError, "No experiment #{id}"
+    end
+
+    # Returns hash of experiments (key is experiment id).
+    #
+    # @see Vanity::Experiment
+    def experiments
+      unless @experiments
+        @experiments = {}
+        @logger.info "Vanity: loading experiments from #{load_path}"
+        Dir[File.join(load_path, "*.rb")].each do |file|
+          Experiment::Base.load self, @loading, file
+        end
+      end
+      @experiments
+    end
+
+    # Reloads all metrics and experiments.  Rails calls this for each request in
+    # development mode.
+    def reload!
+      @experiments = nil
+      @metrics = nil
+      load!
+    end
+
+    # Loads all metrics and experiments.  Rails calls this during
+    # initialization.
+    def load!
+      experiments
+      metrics
+    end
+
+    # Use this instance to access the Redis database.
+    def redis
+      @redis ||= Redis.new(:host=>self.host, :port=>self.port, :db=>self.db,
+                           :password=>self.password, :logger=>self.logger)
+      class << self ; self ; end.send(:define_method, :redis) { @redis }
+      @redis
+    end
+
+    # Switches playground to use MockRedis instead of a live server.
+    # Particularly useful for testing, e.g. if you can't access Redis on your CI
+    # server.  This method has no affect after playground accesses live Redis
+    # server.
+    #
+    # @example Put this in config/environments/test.rb
+    #   config.after_initialize { Vanity.playground.mock! }
+    def mock!
+      @redis ||= MockRedis.new
+    end
+
+    # Returns a metric (raises NameError if no metric with that identifier).
+    #
+    # @see Vanity::Metric
+    # @since 1.1.0
+    def metric(id)
+      metrics[id.to_sym] or raise NameError, "No metric #{id}"
+    end
+
+    # Returns hash of metrics (key is metric id).
+    #
+    # @see Vanity::Metric
+    # @since 1.1.0
+    def metrics
+      unless @metrics
+        @metrics = {}
+        @logger.info "Vanity: loading metrics from #{load_path}/metrics"
+        Dir[File.join(load_path, "metrics/*.rb")].each do |file|
+          Metric.load self, @loading, file
+        end
+      end
+      @metrics
+    end
+
+    # Tracks an action associated with a metric.
+    #
+    # @example
+    #   Vanity.playground.track! :uploaded_video
+    #
+    # @since 1.1.0
+    def track!(id, count = 1)
+      metric(id).track! count
+    end
+  end
+
+  @playground = Playground.new
+  class << self
+
+    # The playground instance.
+    #
+    # @see Vanity::Playground
+    attr_accessor :playground
+
+    # Returns the Vanity context.  For example, when using Rails this would be
+    # the current controller, which can be used to get/set the vanity identity.
+    def context
+      Thread.current[:vanity_context]
+    end
+
+    # Sets the Vanity context.  For example, when using Rails this would be
+    # set by the set_vanity_context before filter (via Vanity::Rails#use_vanity).
+    def context=(context)
+      Thread.current[:vanity_context] = context
+    end
+
+    # Path to template.
+    def template(name)
+      path = File.join(File.dirname(__FILE__), "templates/#{name}")
+      path << ".erb" unless name["."]
+      path
+    end
+
+  end
+end
+
+
+class Object
+
+  # Use this method to access an experiment by name.
+  #
+  # @example
+  #   puts experiment(:text_size).alternatives
+  #
+  # @see Vanity::Playground#experiment
+  # @deprecated
+  def experiment(name)
+    warn "Deprecated. Please call Vanity.playground.experiment directly."
+    Vanity.playground.experiment(name)
+  end
+end

data/lib/vanity/rails.rb

@@ -0,0 +1,22 @@
+require "vanity/rails/helpers"
+require "vanity/rails/testing"
+require "vanity/rails/dashboard"
+
+# Include in controller, add view helper methods.
+ActionController::Base.class_eval do
+  extend Vanity::Rails::UseVanity
+  include Vanity::Rails::Filters
+  helper Vanity::Rails::Helpers
+end
+
+Rails.configuration.after_initialize do
+  # Use Rails logger by default.
+  Vanity.playground.logger ||= ActionController::Base.logger
+  Vanity.playground.load_path = "#{RAILS_ROOT}/experiments"
+
+  # Do this at the very end of initialization, allowing test environment to do
+  # Vanity.playground.mock! before any database access takes place.
+  Rails.configuration.after_initialize do
+    Vanity.playground.load!
+  end
+end

data/lib/vanity/rails/dashboard.rb

@@ -0,0 +1,24 @@
+module Vanity
+  module Rails
+    # Step 1: Add a new resource in config/routes.rb:
+    #   map.vanity "/vanity/:action/:id", :controller=>:vanity
+    #
+    # Step 2: Create a new experiments controller:
+    #   class VanityController < ApplicationController
+    #     include Vanity::Rails::Dashboard
+    #   end
+    #
+    # Step 3: Open your browser to http://localhost:3000/vanity
+    module Dashboard
+      def index
+        render Vanity.template("_report"), :content_type=>Mime::HTML, :layout=>true
+      end
+
+      def chooses
+        exp = Vanity.playground.experiment(params[:e])
+        exp.chooses(exp.alternatives[params[:a].to_i].value)
+        render :partial=>Vanity.template("experiment"), :locals=>{ :experiment=>exp }
+      end
+    end
+  end
+end

data/lib/vanity/rails/helpers.rb

@@ -0,0 +1,158 @@
+module Vanity  
+  # Helper methods for use in your controllers.
+  #
+  # 1) Use Vanity from within your controller:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     use_vanity :current_user end
+  #   end
+  #
+  # 2) Present different options for an A/B test:
+  #
+  #   Get started for only $<%= ab_test :pricing %> a month!
+  #
+  # 3) Measure conversion:
+  #
+  #   def signup
+  #     track! :pricing
+  #     . . .
+  #   end
+  module Rails
+    module UseVanity
+
+    protected
+
+      # Defines the vanity_identity method and the set_identity_context filter.
+      #
+      # Call with the name of a method that returns an object whose identity
+      # will be used as the Vanity identity.  Confusing?  Let's try by example:
+      # 
+      #   class ApplicationController < ActionController::Base
+      #     use_vanity :current_user
+      #
+      #     def current_user
+      #       User.find(session[:user_id])
+      #     end
+      #   end
+      # 
+      # If that method (current_user in this example) returns nil, Vanity will
+      # set the identity for you (using a cookie to remember it across
+      # requests).  It also uses this mechanism if you don't provide an
+      # identity object, by calling use_vanity with no arguments.
+      #
+      # Of course you can also use a block:
+      #   class ProjectController < ApplicationController
+      #     use_vanity { |controller| controller.params[:project_id] }
+      #   end
+      def use_vanity(symbol = nil, &block)
+        if block
+          define_method(:vanity_identity) { block.call(self) }
+        else
+          define_method :vanity_identity do
+            return @vanity_identity if @vanity_identity
+            if symbol && object = send(symbol)
+              @vanity_identity = object.id
+            elsif response # everyday use
+              @vanity_identity = cookies["vanity_id"] || ActiveSupport::SecureRandom.hex(16)
+              cookies["vanity_id"] = { :value=>@vanity_identity, :expires=>1.month.from_now }
+              @vanity_identity
+            else # during functional testing
+              @vanity_identity = "test"
+            end
+          end
+        end
+        around_filter :vanity_context_filter
+        before_filter :vanity_reload_filter unless ::Rails.configuration.cache_classes
+        before_filter :vanity_query_parameter_filter
+      end
+
+    end
+
+    module Filters
+    protected
+
+      # Around filter that sets Vanity.context to controller.
+      def vanity_context_filter
+        previous, Vanity.context = Vanity.context, self
+        yield
+      ensure
+        Vanity.context = previous
+      end
+
+      # This filter allows user to choose alternative in experiment using query
+      # parameter.
+      #
+      # Each alternative has a unique fingerprint (run vanity list command to
+      # see them all).  A request with the _vanity query parameter is
+      # intercepted, the alternative is chosen, and the user redirected to the
+      # same request URL sans _vanity parameter.  This only works for GET
+      # requests.
+      # 
+      # For example, if the user requests the page
+      # http://example.com/?_vanity=2907dac4de, the first alternative of the
+      # :null_abc experiment is chosen and the user redirected to
+      # http://example.com/.
+      def vanity_query_parameter_filter
+        if request.get? && params[:_vanity]
+          hashes = Array(params.delete(:_vanity))
+          Vanity.playground.experiments.each do |id, experiment|
+            if experiment.respond_to?(:alternatives)
+              experiment.alternatives.each do |alt|
+                if hash = hashes.delete(experiment.fingerprint(alt)) 
+                  experiment.chooses alt.value
+                  break
+                end
+              end
+            end
+            break if hashes.empty?
+          end
+          redirect_to url_for(params)
+        end
+      end
+
+      # Before filter to reload Vanity experiments/metrics.  Enabled when
+      # cache_classes is false (typically, testing environment).
+      def vanity_reload_filter
+        Vanity.playground.reload!
+      end
+
+    end
+
+    module Helpers
+
+    # This method returns one of the alternative values in the named A/B test.
+    #
+    # @example A/B two alternatives for a page
+    #   def index
+    #     if ab_test(:new_page) # true/false test
+    #       render action: "new_page"
+    #     else
+    #       render action: "index"
+    #     end
+    #   end
+    # @example Similar, alternative value is page name
+    #   def index
+    #     render action: ab_test(:new_page)
+    #   end
+    # @example A/B test inside ERB template (condition) 
+    #   <%= if ab_test(:banner) %>100% less complexity!<% end %>
+    # @example A/B test inside ERB template (value) 
+    #   <%= ab_test(:greeting) %> <%= current_user.name %>
+    # @example A/B test inside ERB template (capture) 
+    #   <% ab_test :features do |count| %>
+    #     <%= count %> features to choose from!
+    #   <% end %>
+    def ab_test(name, &block)
+      value = Vanity.playground.experiment(name).choose
+      if block
+        content = capture(value, &block)
+        block_called_from_erb?(block) ? concat(content) : content
+      else
+        value
+      end
+    end
+
+    end
+
+  end
+end