staccato 0.0.2 → 0.0.3

data/README.md

@@ -78,6 +78,14 @@ 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'
+    })
+
 ## Google Documentation
 
 https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide

data/lib/staccato.rb

@@ -5,7 +5,18 @@ require 'securerandom'
 
 require "staccato/version"
 
+# The `Staccato` module namespace
+# 
+# @author Tony Pitale
 module Staccato
+  # Build a new tracker instance
+  #   If the first argument is explicitly `nil`, a `NoopTracker` is returned
+  #   which responds to all the same `tracker` methods but does no tracking
+  # 
+  # @param id [String, nil] the id provided by google, i.e., `UA-XXXXXX-Y`
+  # @param client_id [String, Integer, nil] a unique id to track the session of
+  #   an individual user
+  # @return [Staccato::Tracker] a new tracker is returned
   def self.tracker(id, client_id = nil)
     if id.nil?
       Staccato::NoopTracker.new
@@ -14,10 +25,14 @@ module Staccato
     end
   end
 
+  # Build a new random `client_id`
+  # 
+  # @return [String] a random value suitable for use as a `client_id`
   def self.build_client_id
     SecureRandom.uuid
   end
 
+  # The tracking endpoint we use to submit requests to GA
   def self.tracking_uri
     URI('http://www.google-analytics.com/collect')
   end

data/lib/staccato/event.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Event Hit type field definitions
+  # @author Tony Pitale
   class Event
+    # Event field definitions
     FIELDS = {
       category: 'ec',
       action: 'ea',
@@ -9,6 +12,7 @@ module Staccato
 
     include Hit
 
+    # event hit type
     def type
       :event
     end

data/lib/staccato/exception.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Exception Hit type field definitions
+  # @author Tony Pitale
   class Exception
+    # Exception field definitions
     FIELDS = {
       description: 'exd',
       fatal: 'exf'
@@ -12,6 +15,7 @@ module Staccato
       options[:fatal] = 1 if options[:fatal]
     end
 
+    # exception hit type
     def type
       :exception
     end

data/lib/staccato/hit.rb

@@ -1,5 +1,13 @@
 module Staccato
+  # The `Hit` module enables a class to track the appropriate parameters
+  #   to Google Analytics given a defined set of `FIELDS` in a map between
+  #   the option name and its specified GA field name
+  # 
+  # @author Tony Pitale
   module Hit
+    # this module is included into each model hit type
+    #   to share the common behavior required to hit
+    #   the Google Analytics /collect api endpoint
     def self.included(model)
       model.extend Forwardable
 
@@ -10,37 +18,68 @@ module Staccato
       end
     end
 
+    # sets up a new hit
+    # @param tracker [Staccato::Tracker] the tracker to collect to
+    # @param options [Hash] options for the specific hit type
     def initialize(tracker, options = {})
       self.tracker = tracker
       self.options = OptionSet.new(options)
     end
 
+    # return the fields for this hit type
+    # @return [Hash] the field definitions
     def fields
       self.class::FIELDS
     end
 
+    # collects the parameters from options for this hit type
     def params
-      {
-        'v' => 1,
-        'tid' => tracker.id,
-        'cid' => tracker.client_id,
-        'ni' => non_interactive,
-        't' => type.to_s
-      }.merge(Hash[
-        fields.map {|field,key| [key, options[field]]}
-      ]).reject {|_,v| v.nil?}
+      base_params.merge(global_options_params).merge(hit_params).reject {|_,v| v.nil?}
     end
 
+    # is this a non interactive hit
+    # @return [Integer, nil]
     def non_interactive
       1 if options[:non_interactive] # defaults to nil
     end
 
+    # post the hit to GA collection endpoint
+    # @return [Net::HTTPOK] the GA api always returns 200 OK
     def track!
       post(Staccato.tracking_uri, params)
     end
 
+    private
+    # @private
     def post(uri, params = {})
       Net::HTTP.post_form(uri, params)
     end
+
+    # @private
+    def base_params
+      {
+        'v' => 1,
+        'tid' => tracker.id,
+        'cid' => tracker.client_id,
+        'ni' => non_interactive,
+        't' => type.to_s
+      }
+    end
+
+    # @private
+    def global_options_params
+      {
+        'dr' => options[:referrer],
+        'de' => options[:encoding],
+        'ul' => options[:user_language],
+        'xid' => options[:experiment_id],
+        'xvar' => options[:experiment_variant]
+      }
+    end
+
+    # @private
+    def hit_params
+      Hash[fields.map {|field,key| [key, options[field]]}]
+    end
   end
 end

data/lib/staccato/option_set.rb

@@ -1,4 +1,6 @@
 module Staccato
+  # Extends OpenStruct with `[]` access method when
+  #   the current version of ruby does not include it
   class OptionSet < OpenStruct
     unless OpenStruct.instance_methods.include?(:[])
       extend Forwardable

data/lib/staccato/pageview.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Pageview Hit type field definitions
+  # @author Tony Pitale
   class Pageview
+    # Pageview field definitions
     FIELDS = {
       hostname: 'dh',
       path: 'dp',
@@ -8,6 +11,7 @@ module Staccato
 
     include Hit
 
+    # pageview hit type
     def type
       :pageview
     end

data/lib/staccato/social.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Social Hit type field definitions
+  # @author Tony Pitale
   class Social
+    # Social field definitions
     FIELDS = {
       action: 'sa',
       network: 'sn',
@@ -8,6 +11,7 @@ module Staccato
 
     include Hit
 
+    # social hit type
     def type
       :social
     end

data/lib/staccato/timing.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Timing Hit type field definitions
+  # @author Tony Pitale
   class Timing
+    # Timing field definitions
     FIELDS = {
       category: 'utc',
       variable: 'utv',
@@ -9,10 +12,13 @@ module Staccato
 
     include Hit
 
+    # timing hit type
     def type
       :timing
     end
 
+    # tracks the timing hit type
+    # @param block [#call] block is executed and time recorded
     def track!(&block)
       if block_given?
         start_at = Time.now

data/lib/staccato/tracker.rb

@@ -1,64 +1,133 @@
 module Staccato
+  # The `Tracker` class has methods to create all `Hit` types
+  #   using the tracker and client id
+  # 
+  # @author Tony Pitale
   class Tracker
+    # sets up a new tracker
+    # @param id [String] the GA tracker id
+    # @param client_id [String, nil] unique value to track user sessions
     def initialize(id, client_id = nil)
       @id = id
       @client_id = client_id
     end
 
+    # The tracker id for GA
+    # @return [String, nil]
     def id
       @id
     end
 
+    # The unique client id
+    # @return [String]
     def client_id
       @client_id ||= Staccato.build_client_id
     end
 
+    # Track a pageview
+    # 
+    # @param options [Hash] options include:
+    #   * path (optional) the path of the current page view
+    #   * hostname (optional) the hostname of the current page view
+    #   * title (optional) the page title
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def pageview(options = {})
       Staccato::Pageview.new(self, options).track!
     end
 
+    # Track an event
+    # 
+    # @param options [Hash] options include:
+    #   * category (optional)
+    #   * action (optional)
+    #   * label (optional)
+    #   * value (optional)
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def event(options = {})
       Staccato::Event.new(self, options).track!
     end
 
+    # Track a social event such as a Facebook Like or Twitter Share
+    # 
+    # @param options [Hash] options include:
+    #   * action (required) the action taken, e.g., 'like'
+    #   * network (required) the network used, e.g., 'facebook'
+    #   * target (required) the target page path, e.g., '/blog/something-awesome'
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def social(options = {})
       Staccato::Social.new(self, options).track!
     end
 
+    # Track an exception
+    # 
+    # @param options [Hash] options include:
+    #   * description (optional) often the class of exception, e.g., RuntimeException
+    #   * fatal (optional) was the exception fatal? boolean, defaults to false
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def exception(options = {})
       Staccato::Exception.new(self, options).track!
     end
 
+    # Track timing
+    # 
+    # @param options [Hash] options include:
+    #   * category (optional) e.g., 'runtime'
+    #   * variable (optional) e.g., 'database'
+    #   * label (optional) e.g., 'query'
+    #   * time (recommended) the integer time in milliseconds
+    # @param block [#call] if a block is provided, the time it takes to
+    #   run will be recorded and set as the `time` value option
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def timing(options = {}, &block)
       Staccato::Timing.new(self, options).track!(&block)
     end
 
+    # Track an ecommerce transaction
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def transaction(options = {})
       Staccato::Transaction.new(self, options).track!
     end
 
+    # Track an item in an ecommerce transaction
+    # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def transaction_item(options = {})
       Staccato::TransactionItem.new(self, options).track!
     end
   end
 
+  # A tracker which does no tracking
+  #   Useful in testing
   class NoopTracker
+    # (see Tracker#initialize)
     def initialize(*); end
 
+    # (see Tracker#id)
     def id
       nil
     end
 
+    # (see Tracker#client_id)
     def client_id
       nil
     end
 
+    # (see Tracker#pageview)
     def pageview(*); end
+    # (see Tracker#event)
     def event(*); end
+    # (see Tracker#social)
     def social(*); end
+    # (see Tracker#exception)
     def exception(*); end
+    # (see Tracker#timing)
     def timing(*)
       yield if block_given?
     end
+    # (see Tracker#transaction)
+    def transaction(*)
+    end
+    # (see Tracker#transaction_item)
+    def transaction_item(*)
+    end
   end
 end

data/lib/staccato/transaction.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Transaction Hit type field definitions
+  # @author Tony Pitale
   class Transaction
+    # Transaction field definitions
     FIELDS = {
       transaction_id: 'ti',
       affiliation: 'ta',
@@ -11,6 +14,7 @@ module Staccato
 
     include Hit
 
+    # transaction hit type
     def type
       :transaction
     end

data/lib/staccato/transaction_item.rb

@@ -1,5 +1,8 @@
 module Staccato
+  # Item Hit type field definitions for Transactions
+  # @author Tony Pitale
   class TransactionItem
+    # Item field definitions
     FIELDS = {
       transaction_id: 'ti',
       name: 'in',
@@ -12,6 +15,7 @@ module Staccato
 
     include Hit
 
+    # item hit type
     def type
       :item
     end

data/lib/staccato/version.rb

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

data/spec/lib/staccato/pageview_spec.rb

@@ -75,4 +75,24 @@ describe Staccato::Pageview do
       })
     end
   end
+
+  context "with experiment_* options" do
+    let(:pageview) do
+      Staccato::Pageview.new(tracker, {
+        experiment_id: 'ac67afa889',
+        experiment_variant: 'c'
+      })
+    end
+
+    it 'has require params' do
+      pageview.params.should eq({
+        'v' => 1,
+        'tid' => 'UA-XXXX-Y',
+        'cid' => '555',
+        't' => 'pageview',
+        'xid' => 'ac67afa889',
+        'xvar' => 'c'
+      })
+    end
+  end
 end

metadata

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