snogmetrics 0.1.7 → 0.1.8

data/lib/snogmetrics.rb

@@ -10,26 +10,45 @@ require 'snogmetrics/railtie' if defined? Rails::Railtie
 # You should override #kissmetrics_api_key in an initializer to set the
 # KISSmetrics API key.
 #
-# You can also override #use_fake_kissmetrics_api? to provide your own logic for
-# when the real KISSmetrics API and when the fake should be used. The fake API
-# simply outputs all events to the console (if the console is defined). The
-# the default implementation outputs the real API only when 
-# `Rails.env.production?` is true.
+# You can also override #output_strategy to provide your own logic for
+# when the real KISSmetrics API, console.log fake, and array fake should be used.
+# The console_log output strategy outputs all events to the console (if the console is defined).
+# The array output strategy simply logs all events in the _kmq variable.
+# The live output strategy sends calls to the async KISSmetrics JS API.
+#
+# The default implementation outputs the real API only when 
+# `Rails.env.production?` is true, and otherwise uses console.log
 module Snogmetrics
-  VERSION = '0.1.7'
+  VERSION = '0.1.8'
 
   # Returns an instance of KissmetricsApi, which is an interface to the
   # KISSmetrics API. It has the methods #record and #identify, which work just
   # like the corresponding methods in the JavaScript API.
   def km
-    @km_api ||= KissmetricsApi.new(kissmetrics_api_key, session, use_fake_kissmetrics_api?)
+    @km_api ||= KissmetricsApi.new(kissmetrics_api_key, session, output_strategy)
   end
 
   # Override this method to set the KISSmetrics API key
   def kissmetrics_api_key
     ''
   end
+
+  # Override this method to set the output strategy.
+  # Available return values:
+  #
+  # :console_log use console.log to display events pushed to KISSmetrics
+  # :array       store events pushed to KISSmetrics on _kmq
+  # :live        send events to KISSmetrics via the async JS API
+  def output_strategy
+    if use_fake_kissmetrics_api?
+      :console_log
+    else
+      :live
+    end
+  end
   
+  # Deprecated: Prefer overriding #output_strategy to control the output strategy.
+  #
   # Override this method to customize when the real API and when the stub API
   # will be outputted.
   def use_fake_kissmetrics_api?
@@ -39,16 +58,17 @@ module Snogmetrics
       false
     end
   end
+
   
 private
 
   class KissmetricsApi
     # Do not instantiate KissmetricsApi yourself, instead mix in Snogmetrics
     # and use it's #km method to get an instance of KissmetricsApi.
-    def initialize(api_key, session, fake_it)
-      @session = session
-      @api_key = api_key
-      @fake_it = fake_it
+    def initialize(api_key, session, output_strategy)
+      @session         = session
+      @api_key         = api_key
+      @output_strategy = output_strategy
     end
     
     # The equivalent of the `KM.record` method of the JavaScript API. You can
@@ -97,9 +117,9 @@ private
     #
     # Returns the JavaScript needed to send the current state to KISSmetrics.
     # This includes the a JavaScript tag that loads the API code (or a fake API
-    # that sends events to the console if the `fake_it` parameter to #initialize
-    # is true), as well as statements that push the current state onto the 
-    # `_kmq` array.
+    # that sends events to the console or a global array if the `output_strategy`
+    # parameter to #initialize is :console_log or :array), as well as statements
+    # that push the current state onto the `_kmq` array.
     #
     # You can pass the option `:reset` to reset the state, this makes sure that
     # subsequent calls to #js will not send events that have already been sent.
@@ -126,7 +146,7 @@ private
     end
     
     def api_js
-      if @fake_it
+      if @output_strategy == :console_log
         <<-JS
         if (window.console) {
           _kmq = (function(queue) {
@@ -142,8 +162,12 @@ private
           })(_kmq);
         }
         JS
-      else
+      elsif @output_strategy == :live
         %((function(){function _kms(u,d){if(navigator.appName.indexOf("Microsoft")==0 && d)document.write("<scr"+"ipt defer='defer' async='true' src='"+u+"'></scr"+"ipt>");else{var s=document.createElement('script');s.type='text/javascript';s.async=true;s.src=u;(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(s);}}_kms('https://i.kissmetrics.com/i.js');_kms('http'+('https:'==document.location.protocol ? 's://s3.amazonaws.com/' : '://')+'scripts.kissmetrics.com/#{@api_key}.1.js',1);})();)
+      elsif @output_strategy == :array
+        ""
+      else
+        raise "Unknown KISSmetrics output strategy: #{@output_strategy}"
       end
     end
   end

data/spec/snogmetrics_spec.rb

@@ -132,6 +132,45 @@ describe Snogmetrics do
       end
     end
 
+    context 'overriding #output_strategy with :console_log' do
+      it 'outputs calls to console.log' do
+        Rails.stub!(:env).and_return(mock('env', :production? => true))
+        @context.stub!(:output_strategy).and_return(:console_log)
+        @context.km.identify('Joyce')
+        @context.km.js.should_not include('scripts.kissmetrics.com')
+        @context.km.js.should include('console.dir')
+      end
+    end
+
+    context 'overriding #output_strategy with :array' do
+      it 'just stores calls in the _kmq array' do
+        Rails.stub!(:env).and_return(mock('env', :production? => true))
+        @context.stub!(:output_strategy).and_return(:array)
+        @context.km.identify('Joyce')
+        @context.km.js.should_not include('scripts.kissmetrics.com')
+        @context.km.js.should_not include('console.dir')
+      end
+    end
+
+    context 'overriding #output_strategy with :live' do
+      it 'sends calls to KISSmetrics' do
+        Rails.stub!(:env).and_return(mock('env', :production? => true))
+        @context.stub!(:output_strategy).and_return(:live)
+        @context.km.identify('Joyce')
+        @context.km.js.should include('scripts.kissmetrics.com')
+        @context.km.js.should_not include('console.dir')
+      end
+    end
+
+    context 'overriding #output_strategy with something else' do
+      it 'raises' do
+        @context.stub!(:output_strategy).and_return(:something_else)
+        lambda {
+          @context.km.js.should include('scripts.kissmetrics.com')
+        }.should raise_error(RuntimeError, "Unknown KISSmetrics output strategy: something_else")
+      end
+    end
+
     it 'outputs javascript even if there are no events and no identity' do
       @context.km.js.should include('kmq')
     end

metadata

@@ -2,7 +2,7 @@
 name: snogmetrics
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors: 
 - Theo Hultberg
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-27 00:00:00 +02:00
+date: 2011-06-30 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency