RubyGems - smooch - Versions diffs - 0.1.0 - Mend

smooch 0.1.0

Files changed (18) hide show

data/.gitignore ADDED Viewed

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile ADDED Viewed

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+# Specify your gem's dependencies in smooch.gemspec
+gemspec
+gem 'rails', '2.3.5'
+group :test do
+	gem 'rspec', '1.3.0'
+  gem 'rspec-rails', '1.3.2'
+end

data/MIT-LICENSE ADDED Viewed

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Brian Leonard
+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.mdown ADDED Viewed

@@ -0,0 +1,79 @@
+# Smooch
+KISSmetrics is a great tool and the Javascript API has some niceties that the Ruby API doesn't have, but sometimes it's nice to make decisions in the Rails controller or views. Smooch makes this possible while keeping most of the Javascript features.
+Smooch allows you to:
+* Define a user's unique identifier and uses the API to associate it later if not logged in yet
+* Define A/B tests and makes the decision in your Ruby code
+* Record events in your Ruby code
+* Use the same code in your views for development a production but not KISSmetrics about development actions or for other reasons
+* Still use the Javascript API as before if you like
+## Example Usage
+### application_controller.rb
+	class ApplicationController < ActionController::Base
+		kiss :current_user
+	end
+### users_controller.rb
+	def new
+		km.record("Signup page viewed")
+		if km.ab("Show faces in sidebar", ["yes", "no"]) == "yes"
+			@profiles = User.good_looking.limited(5)
+		end
+		@user = User.new
+	end
+	def create
+		@user = User.new(params[:user])
+		if @user.save
+			km.set("User zipcode", @user.zipcode)
+			km.record("Signup converted")
+			redirect_to @user
+		else
+			render :new
+		end
+	end
+### new.erb
+	<%= render 'faces', :users => @profiles if @profiles %>
+	...
+	<%= f.text_field :zipcode
+	<%= submit_tag km.ab("Signup Button Text", ["Go!", "Submit"]) %>
+### application.html.erb
+	<html>
+		<head>
+			...
+			<%= km.script %>
+		</head>
+### config/kissmetrics.yml
+    production:
+      apikey: kiss_metrics_api_key_here
+## Reporting
+`km.script` will report the data to KISSmetrics if there is a line in kissmetrics.yml for your environment. In the above example it would have reported the choices about showing faces in the sidebar and the button text as well as the conversion points noted. This would have all been correlated to the user's new id and have set the zipcode if they were successful in the signup.
+You can also pass a boolean variable into the call as follows: `km.script(tracking_metrics?)`
+We use this to opt-out site admins from our metrics for more relevant results.
+## Techniques
+Smooch replicates some of the A/B behaviors of the KISSmetrics library by using (it's own) cookies to remember decisions and be consistent.
+For any given set of decisions made or events recorded/set, they are simply given to the Javascript API the next time the application layout is rendered. This will use either flash or in-memory depending on when the calls were made.
+Several tactics used from other reporting libraries such as [vanity](https://github.com/assaf/vanity).
+Copyright (c) 2011 Brian Leonard, released under the MIT license

data/Rakefile ADDED Viewed

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+require 'spec/rake/spectask'
+task :default => :spec
+desc "Run all specs in spec directory (excluding plugin specs)"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

data/init.rb ADDED Viewed

	@@ -0,0 +1 @@
1	+ require File.dirname(__FILE__) + '/lib/smooch'

data/lib/smooch.rb ADDED Viewed

@@ -0,0 +1,20 @@
+module Smooch
+  API_KEY = ''
+end
+begin
+  config = YAML.load_file("#{RAILS_ROOT}/config/kissmetrics.yml")
+  Smooch::API_KEY = config[RAILS_ENV]['apikey'] if config[RAILS_ENV]
+rescue
+  puts "Error opening KISSmetrics configuration file."
+end
+require 'smooch/base'
+require 'smooch/helpers'
+require 'smooch/controller'
+ActionController::Base.class_eval do
+  extend Smooch::Controller
+end

data/lib/smooch/base.rb ADDED Viewed

@@ -0,0 +1,191 @@
+module Smooch
+  class Base
+     attr_accessor :controller
+     attr_accessor :view
+     def initialize(controller=nil)
+       self.controller = controller
+       self.view = view
+       @choices = {}
+       @records = {}
+       @sets = {}
+       init_flash
+     end
+     def record(property, hash={})
+       flash[:kiss_metrics] = property.to_s
+       @records[property.to_s] = hash
+     end
+     def init_flash
+       property = flash[:kiss_metrics]
+       return unless property
+       record(property)
+     end
+     def clear_flash
+       flash[:kiss_metrics] = nil
+     end
+     def set(property, value)
+       @sets[property.to_s] = value
+     end
+     def ab(name, choices=nil)
+       val = nil
+       # get from parameter passed in
+       val = get_ab_param(name) unless val
+       val = nil if val and choices and not choices.include?(val)
+       # get from database
+       val = get_ab_database(name) unless val
+       val = nil if val and choices and not choices.include?(val)
+       # get from local storage
+       val = get_ab_cached(name) unless val
+       val = nil if val and choices and not choices.include?(val)
+       # get from cookie
+       val = get_ab_cookie(name) unless val
+       val = nil if val and choices and not choices.include?(val)
+       # pick a random one
+       val = get_ab_random_choice(choices) unless val
+       set_ab_value(name, val)
+     end
+     def key(name)
+       # TODO: by identity?
+       md5 = Digest::MD5.hexdigest("#{name}")[-10,10]
+       "ab_#{md5}"
+     end
+     def get_ab_param(name)
+       return params["_ab"]
+     end
+     def get_ab_random_choice(choices)
+       return nil unless choices
+       choices[rand(choices.size)]
+     end
+     def get_ab_cached(name)
+       @choices[name]
+     end
+     def get_ab_cookie(name)
+       get_cookie(key(name))
+     end
+     def set_ab_value(name, val)
+       set_ab_database(name, val)
+       set_cookie(key(name), val)
+       @choices[name] = val
+       val
+     end
+     # TODO db support
+     def get_ab_database(name)
+       # get_identity / key(name)
+       nil
+     end
+     def set_ab_database(name, val)
+       # get_identity / key(name)
+     end
+     # ------ from controller
+     def get_smooch_identity
+       controller.smooch_identity
+     end
+     def get_kiss_identity
+       controller.kiss_identity
+     end
+     def set_cookie(key, value)
+       cookies[key] = { :value => value, :expires => 2.months.from_now }
+     end
+     def get_cookie(key)
+       cookies[key]
+     end
+     # ------ for view
+     def js(text)
+       text = view.send('h', text)
+       text = view.send('escape_javascript', text)
+       text
+     end
+     def push_record(hash)
+       out = ""
+       hash.each do |key, value|
+          out += "_kmq.push(['record', '#{js(key)}'"
+          unless value.empty?
+            out += ", #{value.as_json}"
+          end
+          out += "]);\n"
+       end
+       out.html_safe!
+     end
+     def push_set(hash)
+       out = ""
+       hash.each do |key, value|
+          out += "_kmq.push(['set', {'#{js(key)}' : '#{js(value)}'}]);\n"
+       end
+       out.html_safe!
+     end
+     def api_key
+       Smooch::API_KEY.blank? ? nil : Smooch::API_KEY
+     end
+     def script(send=true)
+       clear_flash
+       out = <<-JAVASCRIPT
+         <script type="text/javascript">
+           var _kmq = _kmq || [];
+           function _kms(u) {
+             setTimeout(function() {
+               var s = document.createElement('script');
+               var f = document.getElementsByTagName('script')[0];
+               s.type = 'text/javascript';
+               s.async = true;
+               s.src = u;
+               f.parentNode.insertBefore(s, f);
+             }, 1);
+           }
+       JAVASCRIPT
+       if send and api_key.present?
+         out += "_kms('//i.kissmetrics.com/i.js');\n"
+         out += "_kms('//doug1izaerwt3.cloudfront.net/#{api_key}.1.js');\n"
+       end
+       identity = get_kiss_identity
+       out += "_kmq.push(['identify', '#{js(identity)}']);\n" if identity
+       out += push_record(@records)
+       out += push_set(@sets)
+       out += push_set(@choices)
+       out += "</script>\n"
+       out.html_safe!
+     end
+     # ------ for tests
+     def has_record?(property)
+       !@records[property.to_s].nil?
+     end
+     def has_set?(property)
+       !@sets[property.to_s].nil?
+     end
+     def cookies
+       return {} unless controller
+       controller.send(:cookies)
+     end
+     def flash
+       return {} unless controller
+       controller.send(:flash)
+     end
+     def params
+       return {} unless controller
+       controller.send(:params)
+     end
+   end
+ end

data/lib/smooch/controller.rb ADDED Viewed

@@ -0,0 +1,46 @@
+require "digest/md5"
+module Smooch
+  COOKIE_ID = "ab_id"
+  module Controller
+    def kiss(symbol = nil, &block)
+      if block
+        define_method(:smooch_calculate_identity) { block.call(self) }
+      else
+        define_method :smooch_calculate_identity do
+          return @smooch_identity if @smooch_identity
+          if symbol && object = send(symbol)
+            @smooch_identity = object.id
+          elsif response # everyday use
+            @smooch_generated = true
+            @smooch_identity = cookies[COOKIE_ID] || ActiveSupport::SecureRandom.hex(16)
+            cookies[COOKIE_ID] = { :value=>@smooch_identity, :expires=>1.month.from_now }
+            @smooch_identity
+          else
+            @smooch_identity = "test"
+          end
+        end
+      end
+      define_method(:smooch_identity) do
+        smooch_calculate_identity
+      end
+      define_method(:kiss_identity) do
+        val = smooch_calculate_identity
+        return "null" if @smooch_generated
+        val
+      end
+      define_method(:smooch_object) do
+        @smooch_object ||= Smooch::Base.new(self)
+      end
+      define_method(:km) do
+        smooch_object
+      end
+      helper_method :smooch_object
+      helper Smooch::Helpers
+    end
+    protected :kiss
+  end
+end

data/lib/smooch/helpers.rb ADDED Viewed

@@ -0,0 +1,9 @@
+module Smooch
+  module Helpers
+    def km
+      km = smooch_object
+      km.view = self
+      km
+    end
+  end
+end

data/lib/smooch/version.rb ADDED Viewed

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

data/smooch.gemspec ADDED Viewed

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "smooch/version"
+Gem::Specification.new do |s|
+  s.name        = "smooch"
+  s.version     = Smooch::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Brian Leonard"]
+  s.email       = ["brian@bleonard.com"]
+  s.homepage    = ""
+  s.summary     = %q{Smooch interacts with KISS Metrics}
+  s.description = %q{Smooch allows you to make A/B decisions and report them to KISS Metrics.
+    It combines the power of makings these decisions in Ruby code with the enhcanced reporting of the KISS Metrics Javascript.}
+  s.rubyforge_project = "smooch"
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/spec/application.rb ADDED Viewed

@@ -0,0 +1,3 @@
+# Create an application controller to satisfy rspec-rails, a dummy controller
+class ApplicationController < ActionController::Base
+end

data/spec/base_spec.rb ADDED Viewed

@@ -0,0 +1,51 @@
+require "spec_helper"
+class TestSmooch < Smooch::Base
+  @@cookies = {}
+  # override stuff provided by controller
+  def get_cookie(key)
+    @@cookies[key]
+  end
+  def set_cookie(key, name)
+    @@cookies[key] = name
+  end
+end
+describe TestSmooch do
+  describe "#ab" do
+    before(:each) do
+      @km = TestSmooch.new
+      @val = @km.ab("Signup Button Color", ["red", "green"])
+    end
+    it "should return one of the variants" do
+      (@val=="red" || @val=="green").should == true
+    end
+    it "should always be the same" do
+      30.times do
+        @km.ab("Signup Button Color", ["red", "green"]).should == @val
+      end
+    end
+    it "should persist across sessions" do
+      30.times do
+        TestSmooch.new.ab("Signup Button Color", ["red", "green"]).should == @val
+      end
+    end
+    it "should adjust when options change" do
+      @val = @km.ab("Signup Button Color", ["blue", "brown", "orange"])
+      (@val=="blue" || @val=="brown" || @val=="orange").should == true
+      @km.ab("Signup Button Color", ["blue", "brown", "orange"]).should == @val
+    end
+    it "should return previous value without choices" do
+      @km.ab("Signup Button Color").should == @val
+      TestSmooch.new.ab("Signup Button Color").should == @val
+    end
+  end
+  describe "api key" do
+    it "should return the api key from the config file" do
+      km = TestSmooch.new
+      km.api_key.should == "test_key_here"
+    end
+  end
+end

data/spec/config/kissmetrics.yml ADDED Viewed

@@ -0,0 +1,5 @@
+production:
+    apikey: production_key_here
+test:
+    apikey: test_key_here

data/spec/controller_spec.rb ADDED Viewed

@@ -0,0 +1,125 @@
+require "spec_helper"
+class SmoochUser
+  USER_ID = 42
+  def id
+    USER_ID
+  end
+end
+class SmoochController < ActionController::Base
+  def get_km
+    @results = km
+  end
+  def get_identity
+    @results = smooch_identity
+  end
+end
+ActionController::Routing::Routes.draw do |map|
+  map.connect "smooch/:action", :controller => "smooch"
+end
+describe SmoochController, :type => :controller do
+  context "when called kiss with no inputs" do
+    before(:each) do
+      SmoochController.class_eval do
+        kiss
+      end
+    end
+    describe "#smooch_identity" do
+      it "should set a random cookie" do
+        cookies[Smooch::COOKIE_ID].should be_nil
+        get :get_identity
+        cookies[Smooch::COOKIE_ID].should_not be_blank
+      end
+      it "should not change the cookie" do
+        cookies[Smooch::COOKIE_ID] = "nice!"
+        get :get_identity
+        cookies[Smooch::COOKIE_ID].should == "nice!"
+      end
+    end
+    describe "#km" do
+      it "should have a reference to the controller" do
+        get :get_km
+        assigns[:results].controller.should == @controller
+      end
+      it "should use controller to get cookie value" do
+        cookies["whatever"] = "test!"
+        get :get_km
+        assigns[:results].get_cookie("whatever").should == "test!"
+      end
+    end
+    describe "records" do
+      it "should transfer flash property" do
+        flash[:kiss_metrics] = "whatever"
+        get :get_km
+        assigns[:results].has_record?("whatever").should == true
+      end
+    end
+  end
+  context "when kiss called with black" do
+    before(:each) do
+      SmoochController.class_eval do
+        def random_stuff
+          "my_custom_value"
+        end
+        kiss { |controller| controller.random_stuff }
+      end
+    end
+    describe "#smooch_identity" do
+      it "should return custom value" do
+        cookies[Smooch::COOKIE_ID].should be_nil
+        get :get_identity
+        assigns[:results].should == "my_custom_value"
+        cookies[Smooch::COOKIE_ID].should be_nil
+      end
+    end
+  end
+  context "when kiss called with identity method" do
+    before(:each) do
+      SmoochController.class_eval do
+        kiss :current_user
+      end
+    end
+    describe "#smooch_identity" do
+      context "when there is a current user" do
+        before(:each) do
+          SmoochController.class_eval do
+            def current_user
+              SmoochUser.new
+            end
+          end
+        end
+        it "should return the current user id" do
+          cookies[Smooch::COOKIE_ID].should be_nil
+          get :get_identity
+          assigns[:results].should == SmoochUser::USER_ID
+          cookies[Smooch::COOKIE_ID].should be_nil
+        end
+      end
+      context "when there is no current user" do
+        before(:each) do
+          SmoochController.class_eval do
+            def current_user
+              nil
+            end
+          end
+        end
+        it "should set a random cookie" do
+          cookies[Smooch::COOKIE_ID].should be_nil
+          get :get_identity
+          cookies[Smooch::COOKIE_ID].should_not be_blank
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb ADDED Viewed

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+RAILS_ENV = 'test'
+# Load Rails
+require 'active_support'
+require 'action_controller'
+require 'action_mailer'
+require 'rails/version'
+RAILS_ROOT = File.join(File.dirname(__FILE__))
+$:.unshift(RAILS_ROOT)
+ActionController::Base.view_paths = RAILS_ROOT
+require File.join(RAILS_ROOT, 'application')
+ActiveSupport::Dependencies.load_paths << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'spec/autorun'
+require 'spec/rails'
+require 'smooch'
+Spec::Runner.configure do |config|
+end

metadata ADDED Viewed

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: smooch
+version: !ruby/object:Gem::Version
+  hash: 27
+  prerelease:
+  segments:
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors:
+- Brian Leonard
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2011-02-05 00:00:00 -08:00
+default_executable:
+dependencies: []
+description: |-
+  Smooch allows you to make A/B decisions and report them to KISS Metrics.
+      It combines the power of makings these decisions in Ruby code with the enhcanced reporting of the KISS Metrics Javascript.
+email:
+- brian@bleonard.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.mdown
+- Rakefile
+- init.rb
+- lib/smooch.rb
+- lib/smooch/base.rb
+- lib/smooch/controller.rb
+- lib/smooch/helpers.rb
+- lib/smooch/version.rb
+- smooch.gemspec
+- spec/application.rb
+- spec/base_spec.rb
+- spec/config/kissmetrics.yml
+- spec/controller_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 3
+      segments:
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 3
+      segments:
+      - 0
+      version: "0"
+requirements: []
+rubyforge_project: smooch
+rubygems_version: 1.5.0
+signing_key:
+specification_version: 3
+summary: Smooch interacts with KISS Metrics
+test_files:
+- spec/application.rb
+- spec/base_spec.rb
+- spec/config/kissmetrics.yml
+- spec/controller_spec.rb
+- spec/spec_helper.rb