touchstone 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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.markdown

@@ -0,0 +1,84 @@
+Touchstone is a Rails Engine that adds the ability to track advanced metrics for your web app. It is inspired by [this post on the Think Vitamin blog](http://thinkvitamin.com/business/marketing/how-to-get-more-customers/).
+
+Touchstone consists of 3 elements:
+
+## Campaigns
+A campaign records the details of a source from which visitors will sign up to your website. It can be a Google Adwords campaign or a link on your homepage.
+
+## Campaign Visits
+By adding the parameter ?cid= to each link, the visit will be recorded.
+
+## Campaign Signups
+When a visitor visits your website via a link containing ?cid= and then signs up, the sign up is tied back to that visit and that campaign. You can then track the revenue obtained from each visitor against the cost of a particular campaign. 
+
+## Installation
+Add the following line to your Gemfile:
+
+	gem 'touchstone'
+
+Then run `bundle install`
+
+Copy the migrations across to your application by running `touchstone:install:migrations`. This will add a models for the 3 elements set out above.
+
+You will need to mount Touchstone in your application by adding the following line to your `routes.rb` file:
+
+	mount Touchstone::Engine, :at => "/touchstone/"
+	
+Finally, add the following to your `application_controller.rb` file:
+
+	before_filter :set_cookie_and_record_visit
+	
+	private
+	
+	def set_cookie_and_record_visit
+		if params[:cid] && Campaign.find_by_id(params[:cid]) && !CampaignVisit.find_by_request_ip(request.remote_ip)
+			if !cookies['touchstone_campaign_id']
+				cookies['touchstone_campaign_id'] = "#{params[:cid]}"
+				CampaignVisit.create(:campaign_id => params[:cid], :request_ip => request.remote_ip)
+			end
+		end
+	end
+
+## Usage
+Usage is very simple. Assume you are running a Google Adwords campaign for 1 week at a cost of $100. Create this campaign in Touchstone and it will return a campaign ID. Make sure all your links on Adwords contain the parameter at the end `?cid={campaign_id}` where `campaign_id` is the id generated by Touchstone. Please note:
+
+* Campaigns don't need to be paid campaigns, it can be as simple as a link from your homepage or multiple links if A/B testing
+* You can update the campaign cost at any time. All calculations are "on the fly" so you're metrics will update automatically
+
+The installation steps described above will get you going with tracking visits from particular campaigns but you still have some work to do in linking this to your users. Touchstone only really provides a benefit when you track how much revenue your users bring in and then it will compare that to the cost of your campaigns. By way of examples only, you could adopt the following pattern to record a campaign signup:
+
+	class UsersController < ApplicationController
+		...
+		def create
+			@user = User.new(params[:user])
+			if @user.save
+				unless cookies['touchstone_campaign_id'].nil?
+					campaign_id = cookies['touchstone_campaign_id']
+					CampaignSignup.create(:user_id => @user.id, :campaign_id => campaign_id)
+				end
+				flash["notice"] = "Successfully signed up"
+				...
+			end
+		end
+	end
+
+Tracking a user's lifetime value will depend on your transactional logic but assuming a common pattern of a user having a subscription and that subscription containing many transactions, the following could be used:
+
+	class User < ActiveRecord::Base
+		...
+		def lifetime_value
+			total = Array.new
+			self.subscription.transactions.each do |t|
+				total << t.amount
+			end
+			total.inject{|sum,x| sum + x}
+		end
+		...
+	end
+
+## Todo
+
+* Don't constrain Touchstone to an application that only has a Users table. Allow this as a configuration option
+* Automatically load routes and application controller content
+* Improve design
+* Add some tests

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Touchstone'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

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

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/stylesheets/touchstone/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+*/

data/app/assets/stylesheets/touchstone/touchstone.css

@@ -0,0 +1,113 @@
+.touchstone {
+	font: 62.5% "Helvetica Neue", "Lucida Grande", "Trebuchet MS", Verdana, sans-serif;
+	font-weight: normal;
+	-webkit-text-shadow: 0px -1px 0px rgb(68,68,68);
+}
+
+.touchstone .wrapper {
+	width: 960px;
+	margin: 10px auto;
+}
+
+.touchstone h1 {
+	font-size: 3em;
+	margin-bottom: 1em;
+}
+
+.touchstone h2 {
+	font-size: 2.4em;
+	margin-bottom: 1em;
+}
+
+.touchstone h3 {
+	font-size: 2em;
+	margin-bottom: 1em;
+}
+
+.touchstone label {
+	float: left;
+	width: 120px;
+	margin-top: 2px;
+	font-weight: bold;
+}
+
+.touchstone p {
+	font-size: 1.4em;
+	margin-bottom: 1em;
+}
+
+.touchstone table {
+	font-size: 1.4em;
+	border: 1px solid rgb(153,178,183);
+	border-spacing: 0px 0px;
+	width: 100%;
+}
+
+.touchstone thead th {
+	padding: 8px 5px;
+	vertical-align: middle;
+	text-align: left;
+	text-transform: uppercase;
+	border-bottom: 1px solid rgb(153,178,183);
+	border-right: 1px solid rgb(153,178,183);
+	background-color: rgb(213,222,217);
+}
+
+.touchstone td {
+	font-size: 1.2em;
+	padding: 5px;
+	border-bottom: 1px solid rgb(153,178,183);
+	border-right: 1px solid rgb(153,178,183);
+}
+
+.touchstone #new-campaign {
+	float: right;
+	margin-top: 10px;
+}
+
+.touchstone #flash_notice {
+	background-color: #65ce6f;
+	border: 1px solid #00cf13;
+	font-weight: bold;
+	text-align: center;
+	padding: 5px 0;
+	margin: 0 200px 10px 200px;
+}
+
+.touchstone #flash_error {
+	background-color: #ff7272;
+	border: 1px solid #ff1515;
+	font-weight: bold;
+	text-align: center;
+	padding: 5px 0;
+	margin: 0 200px 10px 200px;
+}
+
+.touchstone #campaign-info {
+	margin: -3em 0 0 0;
+	font-size: 0.8em;
+}
+
+.touchstone #campaign-info p {
+	margin-top: -1em;
+}
+
+.touchstone #financials {
+	margin-bottom: 10px;
+}
+
+.touchstone .stats h3 {
+	display: inline;
+}
+
+.touchstone .stats span {
+	color: rgb(153,178,183);
+}
+
+.touchstone .stats h3:not(:first-of-type) {
+	margin-left: 15px;
+}
+
+.touchstone #visits {
+	margin-bottom: 20px;
+}

data/app/controllers/touchstone/application_controller.rb

@@ -0,0 +1,4 @@
+module Touchstone
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/touchstone/campaigns_controller.rb

@@ -0,0 +1,28 @@
+class Touchstone::CampaignsController < ApplicationController
+  
+  layout 'touchstone/touchstone'
+  
+  def index
+    @campaigns = Campaign.all
+  end
+  
+  def new
+    @campaign = Campaign.new
+  end
+  
+  def create
+    @campaign = Campaign.new(params[:campaign])
+    if @campaign.save
+      flash[:notice] = "Campaign added"
+      redirect_to campaigns_url
+    else
+      flash[:error] = "Could not add campaign"
+      redirect_to new_campaign_url
+    end
+  end
+  
+  def show
+    @campaign = Campaign.find(params[:id])
+  end
+  
+end

data/app/helpers/touchstone/application_helper.rb

@@ -0,0 +1,4 @@
+module Touchstone
+  module ApplicationHelper
+  end
+end

data/app/models/campaign.rb

@@ -0,0 +1,44 @@
+class Campaign < ActiveRecord::Base
+  
+  validates :name, :presence => true
+  validates :spend_amount, :presence => true
+  
+  has_many :campaign_signups
+  has_many :campaign_visits
+  
+  attr_accessible :name, :notes, :start_date, :end_date, :spend_amount
+  
+  def revenue
+    if self.campaign_signups.length > 0
+      total = Array.new
+      self.campaign_signups.each do |signup|
+        total << signup.user.lifetime_value # TODO: Fix this
+      end
+      total.inject{|sum,x| sum + x}
+    else
+      0.00
+    end
+  end
+  
+  def roi
+    if self.revenue == 0 || self.spend_amount == 0
+      0.00
+    else
+      ((self.revenue - self.spend_amount) / self.spend_amount) * 100
+    end
+  end
+  
+  def visits
+    self.campaign_visits.count
+  end
+  
+  def conversion_rate
+    signups = self.campaign_signups.count
+    if signups > 0
+      (signups.to_f / self.visits.to_f ) * 100
+    else
+      0.00
+    end
+  end
+  
+end

data/app/models/campaign_signup.rb

@@ -0,0 +1,8 @@
+class CampaignSignup < ActiveRecord::Base
+  
+  belongs_to :campaign, :class_name => "Campaign", :foreign_key => "campaign_id"
+  belongs_to :user, :class_name => "User", :foreign_key => "user_id" # TODO: Fix this
+  
+  attr_accessible :user_id, :campaign_id
+  
+end

data/app/models/campaign_visit.rb

@@ -0,0 +1,7 @@
+class CampaignVisit < ActiveRecord::Base
+  
+  belongs_to :campaign, :class_name => "Campaign", :foreign_key => "campaign_id"
+  
+  attr_accessible :campaign_id, :request_ip
+  
+end

data/app/views/layouts/touchstone/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Touchstone</title>
+  <%= stylesheet_link_tag    "touchstone/application", :media => "all" %>
+  <%= javascript_include_tag "touchstone/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/layouts/touchstone/touchstone.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>Touchstone Metrics</title>
+		<%= stylesheet_link_tag "touchstone/touchstone.css" %>
+	  <%= javascript_include_tag "application.js" %>
+	  <%= csrf_meta_tag %>
+	</head>
+	<body class="touchstone">
+		<div class="wrapper">
+			
+			<section id="flash">
+			  <% flash.each do |key, value| -%>
+			    <div id="flash_<%= key %>"><%= value.html_safe %></div>
+			  <% end -%>
+			</section>
+			
+			<%= yield %>
+			
+		</div><!-- .wrapper -->
+	</body>
+</html>

data/app/views/touchstone/campaigns/index.html.erb

@@ -0,0 +1,26 @@
+<p id="new-campaign"><%= link_to "New campaign", new_campaign_url %></p>
+
+<h1>Campaigns</h1>
+
+<table>
+	<thead>
+		<tr>
+			<th scope="col" width="15%">Campaign ID</th>
+			<th scope="col" width="36%">Name</th>
+			<th scope="col" width="17%">Start date</th>
+			<th scope="col" width="17%">End date</th>
+			<th scope="col" width="15%">Spend amount</th>
+		</tr>
+	</thead>
+	<tbody>
+	<% @campaigns.each do |campaign| %>
+		<tr>
+			<td><%= campaign.id %></td>
+			<td><%= link_to "#{campaign.name}", campaign_url(campaign.id) %></td>
+			<td><%= campaign.start_date.strftime("%d %B %Y") %></td>
+			<td><%= campaign.end_date.strftime("%d %B %Y") %></td>
+			<td>$<%= sprintf("%.2f", campaign.spend_amount) %></td>
+		</tr>
+	<% end %>
+	</tbody>
+</table>

data/app/views/touchstone/campaigns/new.html.erb

@@ -0,0 +1,29 @@
+<h1>New campaign</h1>
+
+<%= form_for @campaign do |f| %>
+	
+	<p>
+		<%= f.label :name %>
+		<%= f.text_field :name %>
+	</p>
+	<p>
+		<%= f.label :notes %>
+		<%= f.text_area :notes %>
+	</p>
+	<p>
+		<%= f.label :start_date %>
+		<%= f.date_select :start_date, :order => [:day, :month, :year] %>
+	</p>
+	<p>
+		<%= f.label :end_date %>
+		<%= f.date_select :end_date, :order => [:day, :month, :year] %>
+	</p>
+	<p>
+		<%= f.label :spend_amount %>
+		<%= f.text_field :spend_amount %>
+	</p>
+	<p>
+		<%= f.submit "Create campaign" %>
+	</p>
+	
+<% end %>

data/app/views/touchstone/campaigns/show.html.erb

@@ -0,0 +1,43 @@
+<p><%= link_to "Home", campaigns_url %></p>
+
+<h1>Campaign - <%= @campaign.name %></h1>
+
+<section id="campaign-info">
+	<p><strong>Campaign ID:</strong> <%= @campaign.id %></p>
+
+	<p><strong>Campaign dates:</strong> From <%= @campaign.start_date.strftime("%d %B %Y") %> to <%= @campaign.end_date.strftime("%d %B %Y") %></p>
+</section><!-- #campaign-info -->
+
+<section id="financials" class="stats">
+	<h3><span class="financial-title">Campaign Spend:</span> $<%= sprintf("%.2f", @campaign.spend_amount) %></h3> 
+	<h3><span class="financial-title">Campaign Revenue:</span> $<%= sprintf("%.2f", @campaign.revenue) %></h3>
+	<h3><span class="financial-title">Return on investment:</span> <%= sprintf("%.2f", @campaign.roi) %>%</h3>
+</section>
+
+<section id="visits" class="stats">
+	<h3><span class="visit-title">Unique Campaign Visits:</span> <%= @campaign.visits %></h3>
+	<h3><span class="visit-title">Conversion Rate:</span> <%= sprintf("%.2f",@campaign.conversion_rate) %>%</h3>
+</section>
+
+<h2>Signups via this campaign</h2>
+
+<table>
+	<thead>
+		<tr>
+			<th scope="col" width="25%">Name</th>
+			<th scope="col" width="30%">Email</th>
+			<th scope="col" width="30%">Registered</th>
+			<th scope="col" width="15%">LTV (inc. VAT)</th>
+		</tr>
+	</thead>
+	<tbody>
+	<% @campaign.campaign_signups.each do |signup| %>
+		<tr>
+			<td><%= signup.user.name %></td>
+			<td><%= signup.user.email %></td>
+			<td><%= time_ago_in_words(signup.user.created_at) %> ago</td>
+			<td>$<%= sprintf("%.2f",signup.user.lifetime_value) %></td>
+		</tr>
+	<% end %>
+	</tbody>
+</table>

data/config/routes.rb

@@ -0,0 +1,5 @@
+Touchstone::Engine.routes.draw do
+  
+  resources :campaigns
+  
+end

data/db/migrate/001_create_touchstone_campaigns.rb

@@ -0,0 +1,14 @@
+class CreateTouchstoneCampaigns < ActiveRecord::Migration
+  
+  def change
+    create_table :campaigns do |t|
+      t.string  :name
+      t.text    :notes
+      t.date    :start_date
+      t.date    :end_date
+      t.float   :spend_amount
+      t.timestamps
+    end
+  end
+  
+end

data/db/migrate/002_create_touchstone_campaign_signups.rb

@@ -0,0 +1,11 @@
+class CreateTouchstoneCampaignSignups < ActiveRecord::Migration
+  
+  def change
+    create_table :campaign_signups do |t|
+      t.integer :user_id
+      t.integer :campaign_id
+      t.timestamps
+    end
+  end
+  
+end

data/db/migrate/003_create_touchstone_campaign_visits.rb

@@ -0,0 +1,13 @@
+class CreateTouchstoneCampaignVisits < ActiveRecord::Migration
+  
+  def change
+    create_table :campaign_visits do |t|
+      t.integer   :campaign_id
+      t.string    :request_ip
+      t.timestamps
+    end
+    
+    add_index :campaign_visits, :request_ip
+  end
+  
+end

data/lib/tasks/touchstone_tasks.rake

@@ -0,0 +1,10 @@
+# require 'thor'
+# include Thor
+# 
+# namespace :touchstone do
+#   
+#   desc "Injects the necessary code into your application to run Touchstone"
+#   task :install do
+#     inject_into_file "#{Rails.root}/config/routes.rb", "mount Touchstone::Engine, :at => '/touchstone/'", :after => "routes.draw do"
+#   end
+# end

data/lib/touchstone/configuration.rb

@@ -0,0 +1,18 @@
+require 'singleton'
+module Touchstone
+  module Configuration
+   
+    extend self
+    
+    attr_accessor :association_name
+    
+    def association_name=name
+      @name = name
+    end
+    
+    def association_name
+      @name || "user"
+    end
+    
+  end
+end

data/lib/touchstone/engine.rb

@@ -0,0 +1,6 @@
+module Touchstone
+  class Engine < ::Rails::Engine
+    isolate_namespace Touchstone
+    
+  end
+end

data/lib/touchstone/version.rb

@@ -0,0 +1,3 @@
+module Touchstone
+  VERSION = "0.1.0"
+end

data/lib/touchstone.rb

@@ -0,0 +1,16 @@
+require "touchstone/engine"
+require "touchstone/configuration"
+
+module Touchstone
+  
+  include Configuration
+  
+  mattr_accessor :app_root
+  
+  class << self
+    def configure &block
+      yield Touchstone::Configuration
+    end
+  end
+  
+end