staccato 0.0.3 → 0.0.4

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## Staccato 0.0.4 ##
+
+*   adds session start/end controls
+*   adds custom dimensions and metrics
+
+    *Tony Pitale*
+
+## Staccato 0.0.3 ##
+
+*   adds YARD documentation
+*   adds context experiment global options
+*   adds language and encoding global options
+*   adds referrer global option
+
+    *Tony Pitale*
+
 ## Staccato 0.0.2 ##
 
 *   adds timing tracking with block timing

data/README.md

@@ -2,6 +2,7 @@
 
 Ruby Google Analytics Measurement
 
+[![Gem Version](https://badge.fury.io/rb/staccato.png)](http://badge.fury.io/rb/staccato)
 [![Build Status](https://travis-ci.org/tpitale/staccato.png?branch=master)](https://travis-ci.org/tpitale/staccato)
 [![Code Climate](https://codeclimate.com/github/tpitale/staccato.png)](https://codeclimate.com/github/tpitale/staccato)
 
@@ -21,70 +22,113 @@ Or install it yourself as:
 
 ## Usage ##
 
-    tracker = Staccato.tracker('UA-XXXX-Y') # REQUIRED, your Google Analytics Tracking ID
+```ruby
+tracker = Staccato.tracker('UA-XXXX-Y') # REQUIRED, your Google Analytics Tracking ID
+```
 
 `#tracker` optionally takes a second param for the `client_id` value
 By default, the `client_id` is set to a random UUID with `SecureRandom.uuid`
 
 ### Track some data ###
 
-    # Track a Pageview (all values optional)
-    tracker.pageview(path: '/page-path', hostname: 'mysite.com', title: 'A Page!')
-
-    # Track an Event (all values optional)
-    tracker.event(category: 'video', action: 'play', label: 'cars', value: 1)
-
-    # Track social activity (all values REQUIRED)
-    tracker.social(action: 'like', network: 'facebook', target: '/something')
-
-    # Track exceptions (all values optional)
-    tracker.exception(description: 'RuntimeException', fatal: true)
-
-    # Track timing (all values optional, but should include time)
-    tracker.timing(category: 'runtime', variable: 'db', label: 'query', time: 50) # time in milliseconds
-
-    tracker.timing(category: 'runtime', variable: 'db', label: 'query') do
-      some_code_here
-    end
-
-    # Track transaction (transaction_id REQUIRED)
-    tracker.transaction({
-      transaction_id: 12345,
-      affiliation: 'clothing',
-      revenue: 17.98,
-      shipping: 2.00,
-      tax: 2.50,
-      currency: 'EUR'
-    })
-
-    # Track transaction item (matching transaction_id and item name REQUIRED)
-    tracker.transaction_item({
-      transaction_id: 12345,
-      name: 'Shirt',
-      price: 8.99,
-      quantity: 2,
-      code: 'afhcka1230',
-      variation: 'red',
-      currency: 'EUR'
-    })
+```ruby
+# Track a Pageview (all values optional)
+tracker.pageview(path: '/page-path', hostname: 'mysite.com', title: 'A Page!')
+
+# Track an Event (all values optional)
+tracker.event(category: 'video', action: 'play', label: 'cars', value: 1)
+
+# Track social activity (all values REQUIRED)
+tracker.social(action: 'like', network: 'facebook', target: '/something')
+
+# Track exceptions (all values optional)
+tracker.exception(description: 'RuntimeException', fatal: true)
+
+# Track timing (all values optional, but should include time)
+tracker.timing(category: 'runtime', variable: 'db', label: 'query', time: 50) # time in milliseconds
+
+tracker.timing(category: 'runtime', variable: 'db', label: 'query') do
+  some_code_here
+end
+
+# Track transaction (transaction_id REQUIRED)
+tracker.transaction({
+  transaction_id: 12345,
+  affiliation: 'clothing',
+  revenue: 17.98,
+  shipping: 2.00,
+  tax: 2.50,
+  currency: 'EUR'
+})
+
+# Track transaction item (matching transaction_id and item name REQUIRED)
+tracker.transaction_item({
+  transaction_id: 12345,
+  name: 'Shirt',
+  price: 8.99,
+  quantity: 2,
+  code: 'afhcka1230',
+  variation: 'red',
+  currency: 'EUR'
+})
+```
+
+Each one of these methods returns a particular `hit` type. To send the tracking information to google analytics, simply call `track!`.
+
+```ruby
+tracker.pageview(path: '/item-120291').track!
+```
 
 ### "Global" Options ###
 
-    # Track a Non-Interactive Event
-    tracker.event(category: 'video', action: 'play', non_interactive: true)
+#### Custom Dimensions and Metrics ####
+
+```ruby
+hit = tracker.pageview('/sports-page-5')
+hit.add_custom_dimension(19, 'Sports')
+hit.add_custom_metric(2, 5)
+hit.track!
+```
+
+The first argument is the slot position. Custom dimensions and metrics have 20 slots or 200 if you're "Premium" account.
+
+The second argument is the value. For dimensions, that's a text value. For metrics it is an integer.
+
+#### Non-Interactive Hit ####
+
+```ruby
+# Track a Non-Interactive Hit
+tracker.event(category: 'video', action: 'play', non_interactive: true)
+```
 
 Non-Interactive events are useful for tracking things like emails sent, or other
 events that are not directly the result of a user's interaction.
 
 The option `non_interactive` is accepted for all methods on `tracker`.
 
-    # Tracking an Experiment
-    #   useful for tracking A/B or Multivariate testing
-    tracker.pageview({
-      path: '/blog',
-      experiment_id: 'a7a8d91df',
-      experiment_variant: 'a'
-    })
+#### Session Control ####
+
+```ruby
+# start a session
+tracker.pageview(path: '/blog', start_session: true)
+
+# end a session
+tracker.pageview(path: '/blog', end_session: true)
+```
+
+Other options are acceptable to start and end a session: `session_start`, `sessoin_end`, and `stop_session`.
+
+#### Content Experiment ####
+
+```ruby
+# Tracking an Experiment
+#   useful for tracking A/B or Multivariate testing
+tracker.pageview({
+  path: '/blog',
+  experiment_id: 'a7a8d91df',
+  experiment_variant: 'a'
+})
+```
 
 ## Google Documentation
 

data/lib/staccato/hit.rb

@@ -34,7 +34,12 @@ module Staccato
 
     # collects the parameters from options for this hit type
     def params
-      base_params.merge(global_options_params).merge(hit_params).reject {|_,v| v.nil?}
+      base_params.
+        merge(global_options_params).
+        merge(hit_params).
+        merge(custom_dimensions).
+        merge(custom_metrics).
+        reject {|_,v| v.nil?}
     end
 
     # is this a non interactive hit
@@ -43,6 +48,31 @@ module Staccato
       1 if options[:non_interactive] # defaults to nil
     end
 
+    def add_custom_dimension(position, value)
+      self.custom_dimensions["cd#{position}"] = value
+    end
+
+    def custom_dimensions
+      @custom_dimensions ||= {}
+    end
+
+    def add_custom_metric(position, value)
+      self.custom_metrics["cm#{position}"] = value
+    end
+
+    def custom_metrics
+      @custom_metrics ||= {}
+    end
+
+    def session_control
+      case
+      when options[:session_start], options[:start_session]
+        'start'
+      when options[:session_end], options[:end_session], options[:stop_session]
+        'end'
+      end
+    end
+
     # post the hit to GA collection endpoint
     # @return [Net::HTTPOK] the GA api always returns 200 OK
     def track!
@@ -62,6 +92,7 @@ module Staccato
         'tid' => tracker.id,
         'cid' => tracker.client_id,
         'ni' => non_interactive,
+        'sc' => session_control,
         't' => type.to_s
       }
     end

data/lib/staccato/version.rb

@@ -1,4 +1,4 @@
 module Staccato
   # The current Staccato VERSION
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/lib/staccato/pageview_spec.rb

@@ -66,7 +66,7 @@ describe Staccato::Pageview do
       Staccato::Pageview.new(tracker, {})
     end
 
-    it 'has require params' do
+    it 'has required params' do
       pageview.params.should eq({
         'v' => 1,
         'tid' => 'UA-XXXX-Y',
@@ -84,7 +84,7 @@ describe Staccato::Pageview do
       })
     end
 
-    it 'has require params' do
+    it 'has experiment id and variant' do
       pageview.params.should eq({
         'v' => 1,
         'tid' => 'UA-XXXX-Y',
@@ -95,4 +95,66 @@ describe Staccato::Pageview do
       })
     end
   end
+
+  context "with session control" do
+    let(:pageview) do
+      Staccato::Pageview.new(tracker, {
+        session_start: true
+      })
+    end
+
+    it 'has session control param' do
+      pageview.params.should eq({
+        'v' => 1,
+        'tid' => 'UA-XXXX-Y',
+        'cid' => '555',
+        't' => 'pageview',
+        'sc' => 'start'
+      })
+    end
+  end
+
+  context "with some custom dimensions" do
+    let(:pageview) do
+      Staccato::Pageview.new(tracker)
+    end
+
+    before(:each) do
+      pageview.add_custom_dimension(19, 'Apple')
+      pageview.add_custom_dimension(8, 'Samsung')
+    end
+
+    it 'has custom dimensions' do
+      pageview.params.should eq({
+        'v' => 1,
+        'tid' => 'UA-XXXX-Y',
+        'cid' => '555',
+        't' => 'pageview',
+        'cd19' => 'Apple',
+        'cd8' => 'Samsung'
+      })
+    end
+  end
+
+  context "with some custom metrics" do
+    let(:pageview) do
+      Staccato::Pageview.new(tracker)
+    end
+
+    before(:each) do
+      pageview.add_custom_metric(12, 42)
+      pageview.add_custom_metric(1, 11)
+    end
+
+    it 'has custom dimensions' do
+      pageview.params.should eq({
+        'v' => 1,
+        'tid' => 'UA-XXXX-Y',
+        'cid' => '555',
+        't' => 'pageview',
+        'cm12' => 42,
+        'cm1' => 11
+      })
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: staccato
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-21 00:00:00.000000000 Z
+date: 2014-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler