i_wonder 0.0.3 → 0.0.4

data/README.rdoc

@@ -2,114 +2,26 @@
 
 Flexible Analytics, and Testing for every corner of your rails application. I read "The Lean Startup" and got inspired. There were a few good solutions, but none of them quite did what I was looking for. I highly recommend you check out Vanity (http://vanity.labnotes.org/) as it is a drop-in solution for many rails apps.
 
-Key Differences of IWonder:
-
-- Events get tracked by session, as well as an optional user and/or account. This allows the tracking of a users history.
-- Tests can be performed against a session (non-user), logged in user, or an entire account. For account based apps, having different versions for different users can be bad.
-- Data is collected periodically. Lots of useful scenerios for this. (info get's deleted, overwritten, etc)
-- Different reports (and some metrics) can be setup and changed without having to modify your code. 
-- Different reports can be generated without coding knowledge.
-- Each hit and visitor comes with a referrer and IP code. Because that events will be transferred to the user when they signup, you can see which campaigns are resulting in actual signups and paid conversions.
-- Because the session events get added to the user when they log in, you avoid false positives on marketing analytics from visitors returning on different devices. If your application has a mobile interface, this basically avoids all your users being logged as visitors twice.
-
-More big plans!
-
-- Long term campaign tracking interface (the events already get logged, but this will make it easier to see results)
-- E-mail open tracking (for application generated e-mails like the 'Welcome E-mail')
-- Feature request buttons. - details coming soon
-
-== Requirements
-
-* Due to performance optimization IWonder must be used with an SQL style DB currently.
-* Rails 3.1 or higher
-* Ability to run hourly rake tasks (rake cron)
-* Ability to run a background worker process (delayed_job)
+More information can be found at https://github.com/forrest/i_wonder/wiki
 
 == Installation
 
-=== Install the Gem
+You can install IWonder with almost no change to your code in 10-15 minutes. Check it out at http://github.com/forrest/i_wonder/wiki/Installation
 
-Add to your <code>Gemfile</code>:
-
-  gem "i_wonder"
+== Usage
   
-and install:
+Usage instructions can be found at https://github.com/forrest/i_wonder/wiki/Usage
   
-  bundle install
   
-=== Migrate the DB
-
-Generate the migration files and migrate your database:
-
-  rake i_wonder:install:migrations
-  rake db:migrate
-
-
-=== Create the dashboard controller
-
-Add the engine to your routes. This is where the dashboard will be hosted
-
-  Rails.application.routes.draw do
-    ...
-    mount IWonder::Engine => "/super_analytics_engine"
-  end
-
-=== Setting up the hourly cron task
-
-This gem hooks into the "<code>rake cron</code>" request. It can't take snapshots of your metrics any faster than this cron is run. We recommend every hour.
-This will be run automatically if you are hosted on Heroku and have the 'hourly cron' add-on enabled.
-
-
-=== Install Dependecies
-
-This Gem requires the Delayed::Job gem. Installation and configuration instructions can be found at http://github.com/tobi/delayed_job.
-
-We also require the highcharts javascript file in your applications asset path. We don't include it because of licencing reasons. It's free for testing and development. You can find it at http://www.highcharts.com/
-
-
-=== Security
-
-IWonder's controllers will run any <code>:before_filters</code> you have set in your application controller. You can easily check for a password or admin status there.
-
-=== Options & Configurations
-
-You can choose to navigate directly to the dashboard. If you want to include a link on your admin page to the i_wonder dashboard, your can access the url with <code>i_wonder.root_url</code> such as:
-
-  <%= link_to "Go to analytics >", i_wonder.root_url %>
-
-
-If you want to configure this gem, add this to an initializer.
-
-  IWonder.configure do |c|
-    c.controllers_to_ignore = []   # These are all the controllers which don't log any events (i_wonder is also ignored)
-    c.only_log_hits_on_200 = true   # By default hits and new visitors won't be logged on anything but a 200 or 304 (not modified). Your custom events will still be recorded.
-    c.back_to_app_link = "/" # this is the link hitting the home button in IWonder will take you to.
-    c.app_name = "My App"
-  end
-
-
-== Usage
-
-=== Event tracking
-
-==== Setting session, user, and account details
+== Contributing & Reporting Issues
 
-This gem will track the visitor with a permanent cookie (will remember them next visit). However, it can also track users and accounts. Simply call one or both of these methods anywhere in the controller. When a user get's added part way through, the :user_id will get filled in for all the previous events for that session. The :new_visitor event for the session will also be removed if the user has an earlier dated :new_visitor event on their account.
+Report a bug at http://github.com/forrest/i_wonder/issues
 
-  i_wonder_for_user_id(user_id)
+Request a feature at http://github.com/forrest/i_wonder/issues
 
-or
-  
-  i_wonder_for_account_id(account_id)
-  
-:hits and :new_visitors will be logged automatically. You can store any additional by calling <code>report!(event_sym, options = {})</code> in the controller.
-You can also log an event from a model with the same method <code>report!(event_sym, options = {})</code>, but you will need to provide the <code>:user_id</code>
-or <code>:account_id</code> in the options, if you want them recorded.
-  
-  
-== Contributing & Reporting Issues
+Contribute code by picking something off the feature request list at http://github.com/forrest/i_wonder/issues
 
-In progress...
+Contribute time by helping with some documentation at http://github.com/forrest/i_wonder/wiki
 
 
 == Licensing

data/app/assets/javascripts/i_wonder/ab_tests.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/assets/javascripts/i_wonder/application.js

@@ -8,3 +8,18 @@
 //= require jquery-ui
 //= require jquery_ujs
 //= require_tree .
+
+
+
+function nested_delete(raw_this){
+   var row = $(raw_this).closest('.deletable_row');
+   row.hide();
+   row.find(".hidden_destroy").val("true");
+}
+
+//this is called when a new row is being inserted from a partial. 
+//It will replace the "new_row_id" with the current timestamp.
+function new_row_inserter(html){
+  var timestamp = new Date().getTime();
+  return html.replace(/new_row_id/g, timestamp)
+}

data/app/assets/stylesheets/i_wonder/ab_tests.css.scss

@@ -0,0 +1,22 @@
+@import "_shared.css.scss";
+
+.main_form.ab_test { min-width:400px;
+
+  #new_goal, #new_group {margin:10px 0; float:right;}
+
+  #ab_test_goals, #ab_test_groups { list-style:decimal; padding:0 0 0 25px; margin:0;
+    li { padding:0px; clear:both;
+      .options {display:inline-block; margin-left:10px;}
+      .delete {float:right;}
+    }
+  }
+}
+
+table#ab_test_summary { background-color:$light_blue_box_background; padding:0px; margin:0px; border-style:solid; border-width:1px 1px 0 0; border-color:$light_blue_box_border;
+  thead {
+    td {background-color:#ddd;}
+  }
+  tr {
+    td {padding:5px; border-style:solid; border-width:0 0 1px 1px; border-color:$light_blue_box_border; text-align:center;}
+  }
+}

data/app/assets/stylesheets/i_wonder/application.css.scss

@@ -7,6 +7,7 @@
  *= require i_wonder/events
  *= require i_wonder/reports
  *= require i_wonder/metrics
+  *= require i_wonder/ab_tests
 */
 
 @import "_shared.css.scss";

data/app/controllers/i_wonder/ab_tests_controller.rb

@@ -0,0 +1,48 @@
+module IWonder
+  class AbTestsController < ApplicationController
+    layout "i_wonder"
+
+    def index
+      @ab_tests = AbTest.all
+    end
+
+    def show
+      @ab_test = AbTest.find(params[:id])
+    end
+
+    def new
+      @ab_test = AbTest.new(params[:ab_test])
+    end
+
+    def create
+      @ab_test = AbTest.new(params[:ab_test])
+
+      if @ab_test.save
+        redirect_to @ab_test, :notice => "Successfully created ABTest"
+      else
+        render "new"
+      end
+    end
+
+    def edit
+      @ab_test = AbTest.find(params[:id])
+      render "edit"
+    end
+
+    def update
+      @ab_test = AbTest.find(params[:id])
+
+      if @ab_test.update_attributes(params[:ab_test])
+        redirect_to @ab_test, :notice => "Successfully updated ABTest"
+      else
+        render "edit"
+      end
+    end
+
+    def destroy
+      @ab_test = AbTest.find(params[:id])
+      @ab_test.destroy
+      redirect_to ab_tests_path, :notice => "ABTest has been destroyed"
+    end
+  end
+end

data/app/controllers/i_wonder/application_controller.rb

@@ -1,4 +1,4 @@
-module IWonder
-  class ApplicationController < ActionController::Base
-  end
-end
+# module IWonder
+#   class ApplicationController < ActionController::Base
+#   end
+# end

data/app/controllers/i_wonder/metrics_controller.rb

@@ -1,49 +1,48 @@
 module IWonder
   class MetricsController < ApplicationController
     layout "i_wonder"
-    
-     def index
-        @metrics = Metric.all
-      end
 
-      def show
-        @metric = Metric.find(params[:id])
-      end
+    def index
+      @metrics = Metric.all
+    end
 
-      def new
-        @metric = Metric.new(params[:metric])
-      end
+    def show
+      @metric = Metric.find(params[:id])
+    end
 
-      def create
-        @metric = Metric.new(params[:metric])
+    def new
+      @metric = Metric.new(params[:metric])
+    end
 
-        if @metric.save
-          redirect_to @metric, :notice => "Successfully created metric"
-        else
-          render "new"
-        end
-      end
+    def create
+      @metric = Metric.new(params[:metric])
 
-      def edit
-        @metric = Metric.find(params[:id])
-        render "edit"
+      if @metric.save
+        redirect_to @metric, :notice => "Successfully created metric"
+      else
+        render "new"
       end
+    end
 
-      def update
-        @metric = Metric.find(params[:id])
+    def edit
+      @metric = Metric.find(params[:id])
+      render "edit"
+    end
 
-        if @metric.update_attributes(params[:metric])
-          redirect_to @metric, :notice => "Successfully updated metric"
-        else
-          render "edit"
-        end
-      end
+    def update
+      @metric = Metric.find(params[:id])
 
-      def destroy
-        @metric = Metric.find(params[:id])
-        @metric.destroy
-        redirect_to metrics_path, :notice => "Metric has been destroyed"
+      if @metric.update_attributes(params[:metric])
+        redirect_to @metric, :notice => "Successfully updated metric"
+      else
+        render "edit"
       end
-    
+    end
+
+    def destroy
+      @metric = Metric.find(params[:id])
+      @metric.destroy
+      redirect_to metrics_path, :notice => "Metric has been destroyed"
+    end
   end
 end

data/app/helpers/i_wonder/ab_tests_helper.rb

@@ -0,0 +1,4 @@
+module IWonder
+  module AbTestsHelper
+  end
+end

data/app/models/i_wonder/ab_test.rb

@@ -0,0 +1,101 @@
+module IWonder
+  class AbTest < ActiveRecord::Base
+    attr_accessible :name, :sym, :description, :ab_test_goals_attributes, :test_applies_to, :test_group_names
+    serialize :options, Hash
+    serialize :test_group_data, Hash
+    
+    has_many :test_group_memberships, :dependent => :destroy
+
+    has_many :ab_test_goals, :dependent => :destroy
+    accepts_nested_attributes_for :ab_test_goals, :allow_destroy => true
+    
+    hash_accessor :options, :test_group_names, :type => :array, :reject_blanks => true
+    
+    validates_presence_of :name, :on => :create, :message => "can't be blank"
+    validates_uniqueness_of :name, :on => :create, :message => "must be unique"
+    validates_presence_of :sym, :on => :create, :message => "can't be blank"
+    validates_format_of :sym, :with => /^[\w\d\_]+$/, :on => :create, :message => "can only contain letters, numbers and underscores"
+    validates_uniqueness_of :sym, :on => :create, :message => "must be unique"
+    validates_inclusion_of :test_applies_to, :in => %w( session user account ), :on => :create, :message => "extension %s is not included in the list"
+    
+    validate :has_two_groups_and_a_goal
+    def has_two_groups_and_a_goal
+      unless test_group_names.length >= 2
+        errors.add(:base, "Must have atleast two test groups")
+      end
+      
+      if ab_test_goals.reject(&:marked_for_destruction?).length == 0
+        errors.add(:base, "Must have atleast one goal")
+      end
+    end
+   
+    def started?
+      test_group_memberships.count > 0
+    end
+    
+    def which_test_group?(current_controller)
+      if(current_group = get_current_group(current_controller))
+        return current_group.test_group_name
+      else
+        test_group = add_to_test_group(randomly_chosen_test_group, current_controller)
+        return test_group.test_group_name
+      end
+    end
+    
+    def assigned_count(test_group_name)
+      self.test_group_memberships.where(:test_group_name => test_group_name).count
+    end
+    
+    def get_results_for(test_group_name, ab_test_goal)
+      scoped_test_group_memberships  = self.test_group_memberships.where(:test_group_name => test_group_name).scoped
+
+      if test_applies_to =~ /account/i
+        event_membership_key = "account_id"
+      elsif test_applies_to =~ /user/i
+        event_membership_key = "user_id"
+      else
+        event_membership_key = "session_id"
+      end
+      
+      scoped_groups_with_events = scoped_test_group_memberships.joins("LEFT JOIN i_wonder_events ON i_wonder_events.#{event_membership_key} = i_wonder_test_group_memberships.member_id")
+      
+      scoped_groups_with_goal_events = ab_test_goal.add_goal_to_query(scoped_groups_with_events)
+      
+      scoped_groups_with_goal_events.count
+    end
+    
+    
+  private
+    
+    def get_current_group(current_controller)
+      if test_applies_to =~ /account/i
+        env = current_controller.request.env
+        test_group_memberships.where(:member_type => "account", :member_id => env[ENV_KEY]["account_id"].to_s).first
+      elsif test_applies_to =~ /user/i
+        env = current_controller.request.env
+        test_group_memberships.where(:member_type => "user", :member_id => env[ENV_KEY]["user_id"].to_s).first
+      else
+        session_id = current_controller.send("cookies")[COOKIE_KEY+Logging::SESSION_KEY_NAME]
+        test_group_memberships.where(:member_type => "session", :member_id => session_id.to_s).first
+      end
+    end
+    
+    def add_to_test_group(test_group_name, current_controller)
+      if test_applies_to =~ /account/i
+        env = current_controller.request.env
+        test_group_memberships.create!(:member_type => "account", :member_id => env[ENV_KEY]["account_id"].to_s, :test_group_name => test_group_name)
+      elsif test_applies_to =~ /user/i
+        env = current_controller.request.env
+        test_group_memberships.create!(:member_type => "user", :member_id => env[ENV_KEY]["user_id"].to_s, :test_group_name => test_group_name)
+      else
+        session_id = current_controller.send("cookies")[COOKIE_KEY+Logging::SESSION_KEY_NAME]
+        test_group_memberships.create!(:member_type => "session", :member_id => session_id.to_s, :test_group_name => test_group_name)
+      end
+    end
+    
+    def randomly_chosen_test_group
+      test_group_names[rand(test_group_names.length)]
+    end
+    
+  end
+end

data/app/models/i_wonder/ab_test_goal.rb

@@ -0,0 +1,49 @@
+module IWonder
+  class AbTestGoal < ActiveRecord::Base
+    belongs_to :ab_test
+    
+    attr_accessible :goal_type, :event_type, :page_view_controller, :page_view_action
+    serialize :options, Hash
+    hash_accessor :options, :goal_type, :default => "Event"
+    hash_accessor :options, :event_type
+    hash_accessor :options, :page_view_controller
+    hash_accessor :options, :page_view_action
+    
+    validates_inclusion_of :goal_type, :in => ["Event", "Page View"]
+    validates_presence_of :event_type, :if => :tracks_event?
+    validates_presence_of :page_view_controller, :if => :tracks_page_view?
+    
+    def tracks_event?
+      goal_type == "Event"
+    end
+    
+    def tracks_page_view?
+      goal_type == "Page View"
+    end
+    
+    def add_goal_to_query(scoped_statement)
+      if tracks_event?
+        sc = scoped_statement.where("i_wonder_events.event_type = ?", event_type)
+      else
+        sc = scoped_statement.where("i_wonder_events.event_type = ? AND controller = ?", "hit", page_view_controller)
+        
+        if page_view_action.present?
+          sc = sc.where("i_wonder_events.action = ?", page_view_action)
+        end
+      end
+      
+      sc.where("i_wonder_events.created_at > ?", self.ab_test.created_at) # event had to come after goal
+    end
+    
+    def to_s
+      if tracks_event?
+        "#{event_type} occurred"
+      elsif page_view_action.present?
+        "#{page_view_controller}##{page_view_action} hit"
+      else
+        "any #{page_view_controller} hit"
+      end
+    end
+    
+  end
+end

data/app/models/i_wonder/event.rb

@@ -15,12 +15,15 @@ module IWonder
         # for all events on the current session, attach the user and session from that first event
         update_all({:user_id => user_id, :session_id => original_session_id}, ["session_id = ? AND user_id IS NULL", session_id])
         
-        # clear our any new_visitor events other than the first one
+        # Change the new_visitor to a return_visit
         if new_visitor_event and original_session_id != session_id
-          Event.where(:user_id => user_id, :event_type => "new_visitor").where("id <> ?", new_visitor_event.id).delete_all
+          update_all({:event_type => "return_visit"}, ["user_id = ? AND event_type = ? AND id <> ?", user_id, "new_visitor", new_visitor_event.id])
         end
         
         
+        # TODO: merge any tests on the session id over to the original session_id
+        # remove any duplicates (going with the original)
+        
         return original_session_id
       end
       # handle_asynchronously :merge_session_to_user

data/app/models/i_wonder/test_group_membership.rb

@@ -0,0 +1,12 @@
+module IWonder
+  class TestGroupMembership < ActiveRecord::Base
+    belongs_to :ab_test
+    
+    validates_presence_of :test_group_name, :on => :create, :message => "can't be blank"
+    validates_inclusion_of :member_type, :in => %w( account user session ), :on => :create
+    validates_presence_of :member_id, :on => :create, :message => "can't be blank"
+    
+    validates_uniqueness_of :ab_test_id, :on => :create, :message => "must be unique for this member", :scope => [:member_type, :member_id]
+    
+  end
+end

data/app/views/i_wonder/ab_tests/_ab_test_goal_row.html.erb

@@ -0,0 +1,23 @@
+<li class="ab_test_goal deletable_row">
+	<%= f.hidden_field :id%>
+	
+	<%= f.select :goal_type, ["Event", "Page View"], {}, :onchange => "var row = $(this).closest('li'); row.find('.options').hide(); if($(this).val()=='Event'){ row.find('#event_options').show(); }else{ row.find('#page_view_options').show(); }" %>
+	
+	<div id="page_view_options" class='options' <% unless f.object.tracks_page_view? %> style="display:none" <% end %> >
+		<%= f.text_field :page_view_controller, :placeholder => "controller", :size => 20 %>
+		
+		<%= f.text_field :page_view_action, :placeholder => "action (optional)", :size => 20 %>
+	</div>
+	
+	<div id="event_options" class='options' <% unless f.object.tracks_event? %> style="display:none" <% end %> >
+		<%= f.text_field :event_type, :placeholder => "event name" %>
+	</div>
+	
+	<% if f.object.new_record? %>
+		<%= link_to_function "", "$(this).closest('li').remove();", :class => "ui-icon ui-icon-circle-close delete" %>
+	<% else%>
+		<%= f.hidden_field :_destroy, :class => "hidden_destroy" %>
+		<%= link_to_function "", "nested_delete(this);", :class => "ui-icon ui-icon-circle-close delete" %>
+	<% end %>
+	
+</li>

data/app/views/i_wonder/ab_tests/_ab_test_goals.html.erb

@@ -0,0 +1,13 @@
+<%= f.fields_for :ab_test_goals, IWonder::AbTestGoal.new, :child_index => "new_row_id" do |f2|%>
+	<%= link_to_function "+ Add Goal", "$('#ab_test_goals').append(new_row_inserter(\"#{j render(:partial => "ab_test_goal_row", :locals => {:f => f2})}\"));", :id => "new_goal" %>
+<% end %>
+
+<h4>Goals</h4>
+
+<ul id="ab_test_goals">
+	<%= f.fields_for :ab_test_goals do |f2|%>
+		<%= render :partial => "ab_test_goal_row", :locals => {:f => f2} %>
+	<% end %>
+</ul>
+
+<br style="clear:both"/>

data/app/views/i_wonder/ab_tests/_ab_test_group_row.html.erb

@@ -0,0 +1,5 @@
+<li class="ab_test_group deletable_row">
+	<%= text_field_tag "ab_test[test_group_names][]", (defined?(test_group_name) ? test_group_name : ""), :placeholder => "Name..." %>
+		
+	<%= link_to_function "", "$(this).closest('li').remove();", :class => "ui-icon ui-icon-circle-close delete" %>
+</li>

data/app/views/i_wonder/ab_tests/_ab_test_groups.html.erb

@@ -0,0 +1,9 @@
+<%= link_to_function "+ Add Group", "$('#ab_test_groups').append(\"#{j render(:partial => "ab_test_group_row")}\");", :id => "new_goal" %>
+
+<h4>Test Groups</h4>
+
+<ul id="ab_test_groups">
+	<%= render :partial => "ab_test_group_row", :collection => f.object.test_group_names, :as => :test_group_name %>
+</ul>
+
+<br style="clear:both"/>

data/app/views/i_wonder/ab_tests/_form.html.erb

@@ -0,0 +1,50 @@
+<%= form_for @ab_test, :html => {:class => "main_form ab_test"} do |f| %>
+	<% if @ab_test.errors.any? %>
+    <div id="error_explanation">
+      <h2><%= pluralize(@ab_test.errors.count, "error") %> prohibited this test from being saved:</h2>
+
+      <ul>
+      <% @ab_test.errors.full_messages.each do |msg| %>
+        <li><%= msg %></li>
+      <% end %>
+      </ul>
+    </div>
+  <% end %>
+	
+	<div class="field">
+		<b>I wonder</b> <%= f.text_field :name, :placeholder => "test name...", :size => 50 %><b>?</b>
+	</div>
+	
+	<div class="field">
+		<%= f.label :description %>
+		<%= f.text_area :description, :rows => 3, :cols => 50%>
+	</div>
+
+	<div class="field">
+		<%= f.label :test_applies_to %>
+		<%= f.select :test_applies_to, [["Visitor", "session"], ["User", "user"], ["Account", "account"]] %><br/>
+		<span class="description">If User or Account is selected but not available, the first option will be returned.</span>
+	</div>
+	
+	
+	<div class="field">
+		<%= f.label :sym, "Code reference symbol" %>
+		<%= f.text_field :sym, :size => 10 %>
+		<span class="description">letters numbers and underscores. NO spaces!</span>
+	</div>
+	
+	<hr/>
+	
+	<%= render :partial => "ab_test_groups", :locals => {:f => f} %>
+	
+	<hr/>
+
+	<%= render :partial => "ab_test_goals", :locals => {:f => f} %>
+	
+	<hr/>
+	
+	<div class="field">
+		<%= f.submit %>
+	</div>
+	
+<% end %>

data/app/views/i_wonder/ab_tests/_show_not_started.html.erb

@@ -0,0 +1,18 @@
+<p>
+	This test hasn't started yet. Use the following code in a controller or view to begin:
+</p>
+
+<br/>
+<p class="description">You can use the group name directly:</p>
+<pre>&lt;%= which_test_group?("<%= @ab_test.sym %>") %&gt;</pre>
+
+<p class="description">or run through different scenarios:</p>
+
+<pre>
+case which_test_group?("<%= @ab_test.sym %>")
+<% for option_name in @ab_test.test_group_names -%>
+when "<%= option_name%>"
+	...
+<% end -%>
+end
+</pre>

data/app/views/i_wonder/ab_tests/_show_report.html.erb

@@ -0,0 +1,26 @@
+<table id="ab_test_summary" cellpadding=0 cellspacing=0>
+	<thead>
+		<tr>
+			<td></td>
+			<td>Assigned</td>
+			
+			<% for ab_test_goal in @ab_test.ab_test_goals do %>
+				<td><%= ab_test_goal %></td>
+			<% end %>
+			
+		</tr>
+	</thead>
+	
+	<% for group_name in @ab_test.test_group_names do %>
+		<tr>
+			<td><%= group_name%></td>
+			<td><%= @ab_test.test_group_memberships.where(:test_group_name => group_name).count %></td>
+			
+			<% for ab_test_goal in @ab_test.ab_test_goals do %>
+				<td><%= @ab_test.get_results_for(group_name, ab_test_goal) %></td>
+			<% end %>
+			
+			
+		</tr>
+	<% end %>
+</table>