saucy-kiss 0.0.1

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+0.0.1
+
+Initial release.  Provides the basic set of KISSmetrics SaaS events:
+
+* Visited Site
+* Signed Up
+* Upgraded
+* Downgraded
+* Billed
+* Canceled

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rspec", "~> 2.3.0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jason Morrison
+
+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.rdoc

@@ -0,0 +1,157 @@
+= saucy-kiss
+
+Saucy-KISS is an extension to the Saucy gem for tracking your SaaS events
+in KISSmetrics.
+
+It depends on the unofficial KISSmetrics gem http://rubygems.org/gems/kissmetrics
+
+== Features and assumptions
+
+We assume that:
+
+* You want the KISSmetrics JS on the page at all times, so you can define
+  events in KISSmetrics, use their Google Analytics tie-in, etc.
+
+* You would like to track events using the JS API as much as possible, to take
+  advantage of KISSmetrics' anonymous identity tracking, automatic handling
+  of the "Visited Site" metric, bot/crawler blacklisting, etc.
+
+By using the kissmetrics gem, we support:
+
+* Testing your KISSmetrics integration points.
+
+* Using the KISSmetrics JS API from the request/response cycle by storing
+  identity, events, and properties in the session and rendering them into your
+  view as JS calls, similar to the Rails flash.
+
+* Using the KISSmetrics HTTP API from outside the request/response cycle (think
+  billing callbacks, or queued operations) delivered directly.  Patches for
+  queued delivery of HTTP API calls (Resque, Delayed::Job, QueueClassic, etc.)
+  are welcome.
+
+== Supported events
+
+Saucy-kiss records all the KISSmetrics SaaS events http://support.kissmetrics.com/apis/saas_events:
+
+* Visited Site (handled automatically by the KISSmetrics JS library)
+* Signed Up
+* Upgraded / Downgraded (distinguised by plan price)
+* Billed
+* Canceled
+
+TODO: Additional events provided by Saucy:
+
+* Viewed Plan List
+* Viewed Plan
+* Invited New User
+* Accepted Invite
+* Tried to Exceed Project Limit
+
+TODO: And events provided by Clearance:
+
+* Signed In
+* Signed Out
+
+TODO: Examples of additional meta-events?:
+
+* Give example of Visit Retention (>1 signins per month with a Visit model and Clearance instrumentation)
+
+== Identity
+
+It will identify users to the current account where ever possible, and as anonymous
+otherwise.  KISSmetrics will correctly handling aliasing between anonymous and
+named identities, and distinguishing between successive named identites, such as
+when you switch accounts.  For more information, see: 
+
+http://support.kissmetrics.com/advanced/identity-management
+
+== Installation
+
+In your Gemfile:
+
+  gem "saucy-kiss" # depend on kissmetrics, snogmetrics
+  gem "snogmetrics", :git => "git://github.com/jasonm/snogmetrics" # only until snogmetrics accepts my patch
+
+Then:
+
+  $ bundle
+
+== Implementation in your application
+
+Add an initializer in config/initializers/saucy_kiss.rb:
+
+    Rails.configuration.after_initialize do
+      Saucy::Notifications.register_observer(Saucy::Kiss::Observer.new({
+        'staging'    => 'abc123',
+        'production' => 'def456'
+      }[Rails.env]))
+    end
+
+Add a filter to each request in ApplicationController:
+
+    before_filter Saucy::Kiss::KissmetricsIdentityControllerFilter
+
+Note: Saucy::Kiss will automatically instantiate the Snogmetrics gem like this:
+
+    api_key = Saucy::Kiss::API_KEYS[Rails.env]
+    session = data[:request].session
+    console_log_output = Rails.env.development?
+    Snogmetrics::KissmetricsApi.new(api_key, session, console_log_output)
+
+and the Kissmetrics gem like this:
+
+  Kissmetrics::HttpClient.new(Saucy::Kiss::API_KEYS[Rails.env])
+
+TODO: Is that ^ still accurate?
+
+== Customization
+
+You may like to customize the events delivered to KISSmetrics.  For example,
+you may want to track the referring ad campaign in a Signed Up event.
+
+To do this, instead of using the Saucy::Kiss::Observer directly,
+create a subclass of the observer and register it instead:
+
+    class MyAppObserver < Saucy::Kiss::Observer
+      def account_created(data)
+        javascript_client(data).record('Signed Up', {
+          'Plan Name' => data[:account].plan.name,
+          'Plan Price' => data[:account].plan.price,
+          'Is Trial Plan?' => data[:account].plan.trial,
+          'Campaign Source' => data[:request].session[:campaign_source]
+        })
+      end
+    end
+
+    Rails.configuration.after_initialize do
+      Saucy::Notifications.register_observer(M)yAppObserver.new({
+        'staging'    => 'abc123',
+        'production' => 'def456'
+      }[Rails.env]))
+    end
+
+== How it works
+
+Saucy accepts observers in its configuration and publishes events for the
+SaaS events it implements.  This gem implements an observer for these events,
+which your application registers in an initializer.
+
+Saucy-kiss distinguishes between in-request events and out-of-request events,
+because it prefers delivering events to KISSmetrics via the JS API where
+possible; this is only possible for in-request events.
+
+== Contributing to saucy-kiss
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Jason Morrison. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec

data/lib/saucy-kiss.rb

@@ -0,0 +1,2 @@
+require 'saucy/kiss/observer'
+require 'saucy/kiss/controller_identity_filter'

data/lib/saucy/kiss/controller_identity_filter.rb

@@ -0,0 +1,13 @@
+module Saucy
+  module Kiss
+    class ControllerIdentityFilter
+      def self.filter(controller)
+        if controller.current_account
+          controller.km.identify("account-#{controller.current_account.id}")
+        else
+          controller.km.identify(nil)
+        end
+      end
+    end
+  end
+end

data/lib/saucy/kiss/observer.rb

@@ -0,0 +1,73 @@
+require 'snogmetrics'
+require 'kissmetrics'
+
+module Saucy
+  module Kiss
+    class Observer
+      def initialize(api_key)
+        @api_key = api_key
+      end
+
+      def plan_viewed(data)
+        javascript_client(data).record('Viewed Plan', {
+          'Plan Name' => data[:plan].name,
+          'Plan Price' => data[:plan].price,
+          'Is Trial Plan?' => data[:plan].trial
+        })
+      end
+
+      def account_created(data)
+        javascript_client(data).record('Signed Up', {
+          'Plan Name' => data[:account].plan.name,
+          'Plan Price' => data[:account].plan.price,
+          'Is Trial Plan?' => data[:account].plan.trial
+        })
+      end
+
+      def plan_upgraded(data)
+        javascript_client(data).record('Upgraded', {
+          'Previous Plan Name' => data[:from_plan].name,
+          'Plan Name' => data[:to_plan].name,
+          'Plan Price' => data[:to_plan].price,
+          'Is Trial Plan?'=> data[:to_plan].trial,
+        })
+      end
+
+      def plan_downgraded(data)
+        javascript_client(data).record('Downgraded', {
+          'Previous Plan Name' => data[:from_plan].name,
+          'Plan Name' => data[:to_plan].name,
+          'Plan Price' => data[:to_plan].price,
+          'Is Trial Plan?'=> data[:to_plan].trial,
+        })
+      end
+
+      def billed(data)
+        account_identifier = "account-#{data[:account].id}"
+        http_client.record(account_identifier, 'Billed', {
+          'Billing Description' => "Monthly billing for #{data[:account].plan.name} plan",
+          'Billing Amount' => data[:account].plan.price
+        })
+      end
+
+      def canceled(data)
+        plan = data[:account].plan
+        javascript_client(data).record('Canceled', {
+          'Plan Name' => plan.name,
+          'Plan Price' => plan.price,
+          'Is Trial Plan?'=> plan.trial
+        })
+      end
+
+      private
+
+      def javascript_client(data)
+        Snogmetrics::KissmetricsApi.new(@api_key, data[:request].session, Rails.env.development?)
+      end
+
+      def http_client
+        Kissmetrics::HttpClient.new(@api_key)
+      end
+    end
+  end
+end

data/spec/saucy/kiss/controller_identity_filter_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe Saucy::Kiss::ControllerIdentityFilter do
+  let(:km) { stub('kissmetrics client', :identify => true) }
+  let(:account) { stub('account', :id => 12345) }
+
+  context "when there is a current_account" do
+    let(:controller) { stub('controller', :km => km, :current_account => account) }
+
+    it "sets identity based on the account if there is a current_account" do
+      controller.should_receive(:km).with()
+      km.should_receive(:identify).with("account-12345")
+
+      Saucy::Kiss::ControllerIdentityFilter.filter(controller)
+    end
+  end
+
+  context "when there is not a current_account" do
+    let(:controller) { stub('controller', :km => km, :current_account => nil) }
+
+    it "clears identity" do
+      controller.should_receive(:km).with()
+      km.should_receive(:identify).with(nil)
+      Saucy::Kiss::ControllerIdentityFilter.filter(controller)
+    end
+  end
+end

data/spec/saucy/kiss/observer_spec.rb

@@ -0,0 +1,91 @@
+require 'spec_helper'
+
+describe Saucy::Kiss::Observer do
+  subject do
+    Saucy::Kiss::Observer.new('abc123')
+  end
+
+  let(:session) { stub('session') }
+  let(:request) { stub('request', :session => session) }
+  let(:javascript_client) { stub('javascript client', :record => true) }
+  let(:http_client) { stub('http client', :record => true) }
+  let(:small_plan) { stub('plan', :name => 'Small', :price => 10, :trial => false) }
+  let(:large_plan) { stub('plan', :name => 'Large', :price => 20, :trial => false) }
+  let(:account) { stub('account', :plan => small_plan, :id => 12345) }
+
+  before(:each) do 
+    Snogmetrics::KissmetricsApi.stub(:new).and_return(javascript_client)
+    Kissmetrics::HttpClient.stub(:new).and_return(http_client)
+  end
+
+  it "tells Snogmetrics to use console.log in development" do
+    with_rails_env(:development) do
+      Snogmetrics::KissmetricsApi.should_receive(:new).
+        with(anything(), anything(), true)
+
+      subject.plan_viewed(:request => request, :plan => small_plan)
+    end
+  end
+
+  it "records a Viewed Plan event through the KISSmetrics JS API for #plan_viewed" do
+    Snogmetrics::KissmetricsApi.should_receive(:new).
+      with('abc123', session, false)
+
+    javascript_client.should_receive(:record).
+      with('Viewed Plan', { 'Plan Name' => 'Small', 'Plan Price' => 10, 'Is Trial Plan?' => false })
+
+    subject.plan_viewed(:request => request, :plan => small_plan)
+  end
+
+  it "records a Signed Up event through the KISSmetrics JS API for #account_created" do 
+    Snogmetrics::KissmetricsApi.should_receive(:new).
+      with('abc123', session, false)
+
+    javascript_client.should_receive(:record).
+      with('Signed Up', { 'Plan Name' => 'Small', 'Plan Price' => 10, 'Is Trial Plan?' => false })
+
+    subject.account_created(:request => request, :account => account)
+  end
+
+  it "records an Upgraded event through the KISSmetrics JS API for #plan_upgraded" do
+    Snogmetrics::KissmetricsApi.should_receive(:new).
+      with('abc123', session, false)
+
+    javascript_client.should_receive(:record).
+      with('Upgraded', { 'Previous Plan Name' => 'Small', 'Plan Name' => 'Large', 'Plan Price' => 20, 'Is Trial Plan?' => false })
+
+    subject.plan_upgraded(:request => request, :account => account, :from_plan => small_plan, :to_plan => large_plan)
+  end
+
+  it "records a Downgraded event through the KISSmetrics JS API for #plan_downgraded" do
+    Snogmetrics::KissmetricsApi.should_receive(:new).
+      with('abc123', session, false)
+
+    javascript_client.should_receive(:record).
+      with('Downgraded', { 'Previous Plan Name' => 'Large', 'Plan Name' => 'Small', 'Plan Price' => 10, 'Is Trial Plan?' => false })
+
+    subject.plan_downgraded(:request => request, :account => account, :from_plan => large_plan, :to_plan => small_plan)
+  end
+
+  it "records a Billed event through the KISSmetrics HTTP API for #billed" do
+    Kissmetrics::HttpClient.should_receive(:new).
+      with('abc123')
+
+    account_identity = "account-#{account.id}"
+
+    http_client.should_receive(:record).
+      with(account_identity, 'Billed', { 'Billing Description' => 'Monthly billing for Small plan', 'Billing Amount' => 10 })
+
+    subject.billed(:request => request, :account => account)
+  end
+
+  it "records a Canceled event through the KISSmetrics JS API for #canceled" do
+    Snogmetrics::KissmetricsApi.should_receive(:new).
+      with('abc123', session, false)
+
+    javascript_client.should_receive(:record).
+      with('Canceled', { 'Plan Name' => 'Small', 'Plan Price' => 10, 'Is Trial Plan?' => false })
+
+    subject.canceled(:request => request, :account => account)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'saucy-kiss'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  config.include RailsEnvHelpers
+end

data/spec/support/rails_env.rb

@@ -0,0 +1,18 @@
+require 'active_support'
+require 'active_support/hash_with_indifferent_access'
+
+class Rails
+  def self.env
+    ActiveSupport::StringInquirer.new($rails_env.to_s || "test")
+  end
+end
+
+module RailsEnvHelpers
+  def with_rails_env(new_env)
+    old_env = $rails_env
+    $rails_env = new_env
+    yield
+  ensure
+    $rails_env = old_env
+  end
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification 
+name: saucy-kiss
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jason Morrison
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-27 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.3.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.6.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.6.2
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "3.0"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: kissmetrics
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.1
+  type: :runtime
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: snogmetrics
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.1.7
+  type: :runtime
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: saucy
+  prerelease: false
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.9.0
+  type: :runtime
+  version_requirements: *id009
+description: Record Saucy SaaS events to KISSmetrics
+email: jason.p.morrison@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- lib/saucy/kiss/controller_identity_filter.rb
+- lib/saucy/kiss/observer.rb
+- lib/saucy-kiss.rb
+- spec/saucy/kiss/controller_identity_filter_spec.rb
+- spec/saucy/kiss/observer_spec.rb
+- spec/spec_helper.rb
+- spec/support/rails_env.rb
+- Gemfile
+- LICENSE.txt
+- README.rdoc
+- CHANGELOG.md
+- Rakefile
+has_rdoc: true
+homepage: http://github.com/jasonm/saucy-kiss
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Record Saucy SaaS events to KISSmetrics
+test_files: []
+