rack-tracker 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c6f2b15cb4ac572305b8421779e956633f04f942
-  data.tar.gz: f9cc033dda73492645c530763bb629be4e505074
+  metadata.gz: b2dfdebdbc6937a3f5b16f873392116a67de22d8
+  data.tar.gz: 69be8ee4f72840aa57eeb30656e1995fde83591a
 SHA512:
-  metadata.gz: 6dc9d9ffa1264d87885c58042f4dafd3362fac3b8d45e6986362ffc8c743fe7dce1ca16a60f80f7bd1255255d6ab7e5985e71a67637cb85ae452adeb3fe545b4
-  data.tar.gz: c4cca8ee9f40adc66b1b9e48497589af502c6a4513dcfe412da8cdc7cf764eaf160e3e890bf979b03890335ffeb81700a1abefb433784a27e64d8b0237f0d58c
+  metadata.gz: 1aafbe6cb3abdece6b939244f995daa9cd1e2c1fb8dfc6fbbcb9e5c488925427e644cd563e70fc63ea002b348aed342afcd9135c40b3cef14c1dc2c1255541b8
+  data.tar.gz: c69c3ccf4ed538f429a56031c322e7bb66f3f9972652bdf0f20b28024a79685fffeb0fff8855eee4f8a0c990db19451d1e348a3007415aa4b2e3277db71a1372

data/README.md

@@ -49,12 +49,45 @@ To issue [Events](https://developers.google.com/analytics/devguides/collection/a
 ```ruby
   def show
     tracker do |t|
-      t.google_analytics category: 'button', action: 'click', label: 'nav-buttons', value: 'X'
+      t.google_analytics :send, { type: 'event', category: 'button', action: 'click', label: 'nav-buttons', value: 'X' }
     end
   end
 ```
 
-The event will show up in the next rendered page. If the next page is a redirect, the event are kept in the session for later use.
+It will render the following to the site source:
+
+```javascript
+  ga('send', { 'hitType': 'event', 'eventCategory': 'button', 'eventAction': 'click', 'eventLabel': 'X' })
+```
+
+#### Ecommerce
+
+You can even trigger ecommerce directly from within your controller:
+
+```ruby
+  def show
+    tracker do |t|
+      t.google_analytics :ecommerce, { type: 'addItem', 'id': '1234', 'affiliation': 'Acme Clothing', 'revenue': '11.99', 'shipping': '5', 'tax': '1.29' }
+    end
+  end
+```
+
+Will give you this:
+
+```javascript
+  ga('ecommerce:addItem', { 'id': '1234', 'affiliation': 'Acme Clothing', 'revenue': '11.99', 'shipping': '5', 'tax': '1.29'  })
+```
+
+To load the `ecommerce`-plugin, add some configuration to the middleware initialization,
+this is _not_ needed for the above to work, but recommened, so you don't have to
+take care of the plugin on your own.
+
+```ruby
+  config.middleware.use(Rack::Tracker) do
+    handler :google_analytics, { tracker: 'U-XXXXX-Y', ecommerce: true}
+  end
+````
+
 
 ### Facebook
 
@@ -67,11 +100,77 @@ To track [Conversions](https://www.facebook.com/help/435189689870514) from the s
 ```ruby
   def show
     tracker do |t|
-      t.facebook '123456789', value: 1, currency: 'EUR'
+      t.facebook :track, { id: '123456789', value: 1, currency: 'EUR' }
     end
   end
 ```
 
+Will result in the following:
+
+```javascript
+  window._fbq.push(["track", "123456789", {'value': 1, 'currency': 'EUR'}]);
+```
+
+## Custom Handlers
+
+Tough we give you Google Analytics and Facebook right out of the box, you might
+be interested adding support for your custom tracking/analytics service.
+
+Writing a handler is straight forward ;) There are just a couple of methods that
+your class needs to implement.
+
+Start with a plain ruby class that inherits from `Rack::Tracker::Handler`
+
+```ruby
+class MyHandler <  Rack::Tracker::Handler
+  ...
+end
+```
+
+Second we need a method called `#render` which will take care of rendering a
+template.
+
+```ruby
+def render
+  Tilt.new( File.join( File.dirname(__FILE__), 'template' 'my_handler.erb') ).render(self)
+end
+```
+
+This will render the `template/my_handler.erb` and inject the result into the source. You
+can be creative about where the template is stored, we tend to have them around
+our actual handler code.
+
+```erb
+<script>
+  console.log('my tracker: ' + <%= options.to_json %>)
+</script>
+```
+
+Lets give it a try! We need to mount our new handler in the `Rack::Tracker` middleware
+
+```ruby
+  config.middleware.use(Rack::Tracker) do
+    handler MyTracker, { awesome: true }
+  end
+````
+
+Everything you're passing to the `handler` will be availble as `#options` in your
+template, You'll also gain access to the `env`-hash belonging to the current request.
+
+Run your application and make a request, the result of the above template can be
+found right before `</head>`. You can change the position in your handler-code:
+
+```ruby
+class MyHandler <  Rack::Tracker::Handler
+  self.position = :body
+
+  ...
+end
+```
+
+The snippot will then be rendered right before `</body>`.
+
+
 ## Contributing
 
 1. Fork it ( http://github.com/railslove/rack-tracker/fork )

data/lib/rack/tracker/controller.rb

@@ -2,7 +2,9 @@ module Rack
   class Tracker
     module Controller
       def tracker(&block)
-        yield(Rack::Tracker::HandlerDelegator.new(env)) if block_given?
+        if block_given?
+          yield(Rack::Tracker::HandlerDelegator.new(env)).keys.map(&:to_sym)
+        end
       end
     end
   end

data/lib/rack/tracker/facebook/facebook.rb

@@ -1,13 +1,7 @@
 class Rack::Tracker::Facebook < Rack::Tracker::Handler
   class Event < OpenStruct
-    attr_reader :id
-    def initialize(id, attributes = {})
-      @id = id
-      super(attributes)
-    end
-
     def write
-      ['track', @id, to_h.compact].to_json
+      ['track', self.id, to_h.except(:id).compact].to_json
     end
   end
 
@@ -18,7 +12,7 @@ class Rack::Tracker::Facebook < Rack::Tracker::Handler
   end
 
   def self.track(name, *event)
-    { name.to_s => [Event.new(*event)] }
+    { name.to_s => [Event.new(event.last)] }
   end
 
 end

data/lib/rack/tracker/google_analytics/google_analytics.rb

@@ -1,21 +1,26 @@
 class Rack::Tracker::GoogleAnalytics < Rack::Tracker::Handler
-  class Event < OpenStruct
+  class Send < OpenStruct
+    def initialize(attrs = {})
+      attrs.reverse_merge!(type: 'event')
+      super
+    end
+
     def write
       ['send', event].to_json.gsub(/\[|\]/, '')
     end
 
     def event
-      { hitType: 'event' }.merge(attributes).compact
+      { hitType: self.type }.merge(attributes).compact
     end
 
     def attributes
-      Hash[to_h.map { |k,v| ['event' + k.to_s.capitalize, v] }]
+      Hash[to_h.slice(:category, :action, :label, :value).map { |k,v| [self.type.to_s + k.to_s.capitalize, v] }]
     end
   end
 
-  class Ecommerce < Struct.new(:action, :payload)
+  class Ecommerce < OpenStruct
     def write
-      [self.action, self.payload.compact].to_json.gsub(/\[|\]/, '')
+      ["ecommerce:#{self.type}", self.to_h.except(:type).compact].to_json.gsub(/\[|\]/, '')
     end
   end
 
@@ -27,7 +32,7 @@ class Rack::Tracker::GoogleAnalytics < Rack::Tracker::Handler
     Tilt.new( File.join( File.dirname(__FILE__), 'template', 'google_analytics.erb') ).render(self)
   end
 
-  def self.track(name, event)
-    { name.to_s => [Event.new(event)] }
+  def self.track(name, *event)
+    { name.to_s => [Send.new(event.last)] }
   end
 end

data/lib/rack/tracker/version.rb

@@ -1,5 +1,5 @@
 module Rack
   class Tracker
-    VERSION = "0.0.4"
+    VERSION = "0.1.0"
   end
 end

data/spec/handler/facebook_spec.rb

@@ -1,7 +1,7 @@
 RSpec.describe Rack::Tracker::Facebook do
   describe Rack::Tracker::Facebook::Event do
 
-    subject { described_class.new('id', {foo: 'bar'}) }
+    subject { described_class.new({id: 'id', foo: 'bar'}) }
 
     describe '#write' do
       specify { expect(subject.write).to eq(['track', 'id', {foo: 'bar'}].to_json) }
@@ -36,10 +36,11 @@ RSpec.describe Rack::Tracker::Facebook do
         'tracker' => {
         'facebook' =>
           [
-            Rack::Tracker::Facebook::Event.new('123456789', {
+            Rack::Tracker::Facebook::Event.new(
+              'id'=> '123456789',
              'value' => '23',
              'currency' => 'EUR'
-            })
+            )
           ]
         }
       }

data/spec/handler/google_analytics_spec.rb

@@ -14,7 +14,7 @@ RSpec.describe Rack::Tracker::GoogleAnalytics do
       def env
         {'tracker' => {
           'google_analytics' => [
-            Rack::Tracker::GoogleAnalytics::Event.new(category: "Users", action: "Login", label: "Standard")
+            Rack::Tracker::GoogleAnalytics::Send.new(category: "Users", action: "Login", label: "Standard")
           ]
         }}
       end
@@ -28,7 +28,7 @@ RSpec.describe Rack::Tracker::GoogleAnalytics do
     describe "with a event value" do
       def env
         {'tracker' => { 'google_analytics' => [
-          Rack::Tracker::GoogleAnalytics::Event.new(category: "Users", action: "Login", label: "Standard", value: 5)
+          Rack::Tracker::GoogleAnalytics::Send.new(category: "Users", action: "Login", label: "Standard", value: 5)
         ]}}
       end
 
@@ -44,7 +44,7 @@ RSpec.describe Rack::Tracker::GoogleAnalytics do
       def env
         {'tracker' => {
           'google_analytics' => [
-            Rack::Tracker::GoogleAnalytics::Ecommerce.new('ecommerce:addItem', {id: '1234', affiliation: 'Acme Clothing', revenue: 11.99, shipping: '5', tax: '1.29', currency: 'EUR'})
+            Rack::Tracker::GoogleAnalytics::Ecommerce.new({type: 'addItem', id: '1234', affiliation: 'Acme Clothing', revenue: 11.99, shipping: '5', tax: '1.29', currency: 'EUR'})
           ]
         }}
       end

data/spec/support/metal_controller.rb

@@ -17,7 +17,7 @@ class MetalController < ActionController::Metal
 
   def facebook
     tracker do |t|
-      t.facebook 'conversion-event', { value: '1', currency: 'EUR' }
+      t.facebook :track, { id: 'conversion-event', value: '1', currency: 'EUR' }
     end
     render "metal/index"
   end

data/spec/tracker/controller_spec.rb

@@ -1,31 +1,36 @@
-class SomeController
+TestController = Struct.new(:env) do
   include Rack::Tracker::Controller
 
-  attr_accessor :env
-
-  def initialize
-    @env = {}
-  end
-
   def index
     tracker do |t|
-      t.google_analytics category: 'foo'
+      t.google_analytics :send, category: 'foo'
     end
   end
 end
 
 
 RSpec.describe Rack::Tracker::Controller do
-  context 'controller' do
-    let(:event) { Rack::Tracker::GoogleAnalytics::Event.new(category: 'foo') }
+  describe '#tracker' do
+    let(:event) { Rack::Tracker::GoogleAnalytics::Send.new(category: 'foo') }
+    let(:controller) { TestController.new({}) }
+
+    context 'controller' do
+      it 'writes the event into env' do
+        expect {
+          controller.index
+        }.to change {
+          controller.env
+        }.from({}).to('tracker' => {'google_analytics' => [event]})
+      end
 
-    it 'writes the event into env' do
-      controller = SomeController.new
-      expect {
-        controller.index
-      }.to change {
-        controller.env
-      }.from({}).to('tracker' => {'google_analytics' => [event]})
+      it 'returns only the handlers' do
+        expect(
+          controller.tracker do |t|
+            t.google_analytics category: 'foo'
+            t.facebook some: 'thing'
+          end
+        ).to eql([:google_analytics, :facebook])
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-tracker
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Lars Brillert