staccato 0.0.4 → 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDM3ZjczOTg3NDUzNWUyZmUxMzI5ZWZhMzEwYmVlMjYyMmY4N2M5YQ==
+  data.tar.gz: !binary |-
+    NGUwOTE4YWIyNWE0ZGRjYjlmMzMxNzlmNzY3ZDJkMzMxMDk5ZjhlMw==
+SHA512:
+  metadata.gz: !binary |-
+    MTdhMzc1NDQ0M2I1ZThiYTVjYTg5ZjFmZmRlY2NlMTdiNDJmODQxZTQwODU0
+    MTY5MDgyMjg1NjZkNjE2ODdmM2JiNjgxN2ZhY2EwOWVmNGY4NDI4N2Q0OTky
+    YThkMGMyYTM3Y2UxMDQ2OWJlYTFjMTcxMTliYThlZTU2ZTNjY2M=
+  data.tar.gz: !binary |-
+    NGIyZDcxMzVmNzE0NTIwOGQxZjY0MDQyNmEyYjM5NDhjY2EzOTc3MTMyNGJi
+    YmI1YTRiZTZiOTkzOWQwYmNmZDVlZmJkY2NkOTY2Zjc0YTBmMmQ1NTRkNjcw
+    NTdkYmMwNjhjZTcyNjIwMWU3NzU2OTZkMzBjZDdkZjc5ZDlkMzY=

data/.ruby-version

@@ -1 +1 @@
-1.9.3-p448
+1.9.3

data/.travis.yml

@@ -2,4 +2,6 @@ language: ruby
 rvm:
   - 1.9.2
   - 1.9.3
+  - 2.0.0
+  - 2.1.0
 script: bundle exec rake

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## Staccato 0.1.0 ##
+
+*   adds support for all global hit options in any hit type
+*   adds default hit options at the tracker level
+*   adds proper handling of boolean values into 1/0
+*   have travis-ci run 2.0, 2.1 rubies
+
+    *Tony Pitale*
+
+*   adds user_ip/user_agent *@medullan*
+
 ## Staccato 0.0.4 ##
 
 *   adds session start/end controls

data/README.md

@@ -1,11 +1,16 @@
 # Staccato
 
-Ruby Google Analytics Measurement
+Ruby library to track into the official Google Analytics Measurement Protocol
+
+https://developers.google.com/analytics/devguides/collection/protocol/v1/
+
+**NOTE:** The Measurement Protocol is part of Universal Analytics, which is currently available in public beta. Data from the measurement protocol will only be processed in Universal Analytics enabled properties.
 
 [![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)
 
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -73,18 +78,70 @@ tracker.transaction_item({
 })
 ```
 
-Each one of these methods returns a particular `hit` type. To send the tracking information to google analytics, simply call `track!`.
+### "Global" Options ###
+
+Any of the options on the parameters list (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters) that are accepted on ALL hit types can be set as options on any of the hits.
 
 ```ruby
-tracker.pageview(path: '/item-120291').track!
+tracker.pageview(path: '/video/1235', flash_version: 'v1.2.3')
 ```
 
-### "Global" Options ###
+Flash Version is a global option in the example above.
+
+**Note:** There are a few options that if used will override global options:
+
+* document_path: overriden by `path` in pageviews
+* document_hostname: overriden by `hostname` in pageviews
+* document_title: overriden by `title` in pageviews
+
+These are holdovers from the original design, where `pageview` is a hit type that can take any/all of the optional parameters. `path`, `hostname`, and `title` are slightly nicer to use on `pageview`.
+
+The complete list at this time:
+
+```ruby
+Staccato::Hit::GLOBAL_OPTIONS.keys # =>
+
+[:anonymize_ip,
+ :queue_time,
+ :cache_buster,
+ :user_id,
+ :user_ip,
+ :user_agent,
+ :referrer,
+ :campaign_name,
+ :campaign_source,
+ :campaign_medium,
+ :campaign_keyword,
+ :campaign_content,
+ :campaign_id,
+ :adwords_id,
+ :display_ads_id,
+ :screen_resolution,
+ :viewport_size,
+ :screen_colors,
+ :user_language,
+ :java_enabled,
+ :flash_version,
+ :document_location,
+ :document_encoding,
+ :document_hostname,
+ :document_path,
+ :document_title,
+ :link_id,
+ :application_name,
+ :application_version,
+ :application_id,
+ :application_installer_id,
+ :experiment_id,
+ :experiment_variant]
+```
+
+Boolean options like `anonymize_ip` will be converted from `true`/`false` into `1`/`0` as per the tracking API docs.
 
 #### Custom Dimensions and Metrics ####
 
 ```ruby
-hit = tracker.pageview('/sports-page-5')
+hit = Staccato::Pageview.new(tracker, '/sports-page-5')
 hit.add_custom_dimension(19, 'Sports')
 hit.add_custom_metric(2, 5)
 hit.track!
@@ -130,6 +187,19 @@ tracker.pageview({
 })
 ```
 
+## Tracker Hit Defaults ##
+
+Global parameters can be set as defaults on the tracker, and will be used for all hits (unless overwritten by parameters set directly on a hit).
+
+The following example creates a tracker with a default hostname. The two pageviews will track the default hostname and the page path passed in.
+
+```ruby
+tracker = Staccato.tracker('UA-XXXX-Y', client_id, {document_hostname: 'example.com'})
+
+tracker.pageview(path: '/videos/123')
+tracker.pageview(path: '/videos/987')
+```
+
 ## Google Documentation
 
 https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide

data/lib/staccato.rb

@@ -17,11 +17,11 @@ module Staccato
   # @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)
+  def self.tracker(id, client_id = nil, hit_options = {})
     if id.nil?
       Staccato::NoopTracker.new
     else
-      Staccato::Tracker.new(id, client_id)
+      Staccato::Tracker.new(id, client_id, hit_options)
     end
   end
 

data/lib/staccato/exception.rb

@@ -10,14 +10,13 @@ module Staccato
 
     include Hit
 
-    def initialize(*)
-      super
-      options[:fatal] = 1 if options[:fatal]
-    end
-
     # exception hit type
     def type
       :exception
     end
+
+    def boolean_fields
+      super << :fatal
+    end
   end
 end

data/lib/staccato/hit.rb

@@ -2,7 +2,7 @@ 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
@@ -18,12 +18,66 @@ module Staccato
       end
     end
 
+    GLOBAL_OPTIONS = {
+      anonymize_ip: 'aip', # boolean
+      queue_time: 'qt', # integer
+      cache_buster: 'z',
+      user_id: 'uid', # a known user's id
+
+      # Session, works with session control
+      user_ip: 'uip',
+      user_agent: 'ua',
+
+      # Traffic Sources
+      referrer: 'dr',
+      campaign_name: 'cn',
+      campaign_source: 'cs',
+      campaign_medium: 'cm',
+      campaign_keyword: 'ck',
+      campaign_content: 'cc',
+      campaign_id: 'ci',
+      adwords_id: 'gclid',
+      display_ads_id: 'dclid',
+
+      # System Info
+      screen_resolution: 'sr',
+      viewport_size: 'vp',
+      screen_colors: 'sd',
+      user_language: 'ul',
+      java_enabled: 'je', # boolean
+      flash_version: 'fl',
+      non_interactive: 'ni', # boolean
+      document_location: 'dl',
+      document_encoding: 'de', # duplicate of encoding
+      document_hostname: 'dh', # duplicate of hostname
+      document_path: 'dp', # duplicate of path
+      document_title: 'dt', # duplicate of title
+      screen_name: 'cd', # screen name is not related to custom dimensions
+      link_id: 'linkid',
+
+      # App Tracking
+      application_name: 'an',
+      application_id: 'aid',
+      application_installer_id: 'aiid',
+      application_version: 'av',
+
+      # Content Experiments
+      experiment_id: 'xid',
+      experiment_variant: 'xvar'
+    }
+
+    BOOLEAN_FIELDS = [
+      :non_interactive,
+      :anonymize_ip,
+      :java_enabled
+    ]
+
     # 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)
+      self.options = OptionSet.new(convert_booleans(options))
     end
 
     # return the fields for this hit type
@@ -35,6 +89,7 @@ module Staccato
     # collects the parameters from options for this hit type
     def params
       base_params.
+        merge(tracker_default_params).
         merge(global_options_params).
         merge(hit_params).
         merge(custom_dimensions).
@@ -42,12 +97,6 @@ module Staccato
         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
-
     def add_custom_dimension(position, value)
       self.custom_dimensions["cd#{position}"] = value
     end
@@ -85,13 +134,41 @@ module Staccato
       Net::HTTP.post_form(uri, params)
     end
 
+    def convert_booleans(hash)
+      hash.each_pair.with_object({}, &method(:convert_boolean))
+    end
+
+    def convert_boolean((k,v), hash)
+      hash[k] = boolean_field?(k) ? integer_for(v) : v
+    end
+
+    def boolean_fields
+      BOOLEAN_FIELDS
+    end
+
+    def boolean_field?(key)
+      boolean_fields.include?(key)
+    end
+
+    def integer_for(value)
+      case value
+      when Integer
+        value
+      when TrueClass
+        1
+      when FalseClass
+        0
+      when NilClass
+        nil
+      end
+    end
+
     # @private
     def base_params
       {
-        'v' => 1,
-        'tid' => tracker.id,
-        'cid' => tracker.client_id,
-        'ni' => non_interactive,
+        'v' => 1, # protocol version
+        'tid' => tracker.id, # tracking/web_property id
+        'cid' => tracker.client_id, # unique client id
         'sc' => session_control,
         't' => type.to_s
       }
@@ -99,18 +176,34 @@ module Staccato
 
     # @private
     def global_options_params
-      {
-        'dr' => options[:referrer],
-        'de' => options[:encoding],
-        'ul' => options[:user_language],
-        'xid' => options[:experiment_id],
-        'xvar' => options[:experiment_variant]
-      }
+      Hash[
+        options.map { |k,v|
+          [GLOBAL_OPTIONS[k], v] if global_option?(k)
+        }.compact
+      ]
+    end
+
+    # @private
+    def tracker_default_params
+      Hash[
+        tracker.hit_defaults.map { |k,v|
+          [GLOBAL_OPTIONS[k], v] if global_option?(k)
+        }.compact
+      ]
+    end
+
+    # @private
+    def global_option?(key)
+      GLOBAL_OPTIONS.keys.include?(key)
     end
 
     # @private
     def hit_params
-      Hash[fields.map {|field,key| [key, options[field]]}]
+      Hash[
+        fields.map { |field,key|
+          [key, options[field]] unless options[field].nil?
+        }.compact
+      ]
     end
   end
 end

data/lib/staccato/option_set.rb

@@ -2,9 +2,15 @@ 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
+    extend Forwardable
+
+    unless OpenStruct.instance_methods.include?(:each)
+      include Enumerable
 
+      def_delegators :@table, :each
+    end
+
+    unless OpenStruct.instance_methods.include?(:[])
       def_delegators :@table, :[], :[]=
     end
   end

data/lib/staccato/pageview.rb

@@ -4,9 +4,9 @@ module Staccato
   class Pageview
     # Pageview field definitions
     FIELDS = {
-      hostname: 'dh',
-      path: 'dp',
-      title: 'dt'
+      hostname: 'dh', # moved to GLOBAL_OPTIONS
+      path: 'dp', # moved to GLOBAL_OPTIONS
+      title: 'dt' # moved to GLOBAL_OPTIONS
     }
 
     include Hit

data/lib/staccato/timing.rb

@@ -7,7 +7,15 @@ module Staccato
       category: 'utc',
       variable: 'utv',
       label: 'utl',
-      time: 'utt'
+      time: 'utt',
+
+      # more specific timings
+      page_load_time: 'plt',
+      dns_time: 'dns',
+      page_download_time: 'pdt',
+      redirect_response_time: 'rrt',
+      tcp_connect_time: 'tcp',
+      server_response_time: 'srt'
     }
 
     include Hit

data/lib/staccato/tracker.rb

@@ -4,12 +4,16 @@ module Staccato
   # 
   # @author Tony Pitale
   class Tracker
+    attr_accessor :hit_defaults
+
     # 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)
+    def initialize(id, client_id = nil, hit_defaults = {})
       @id = id
       @client_id = client_id
+
+      self.hit_defaults = hit_defaults
     end
 
     # The tracker id for GA
@@ -75,8 +79,15 @@ module Staccato
     #   * variable (optional) e.g., 'database'
     #   * label (optional) e.g., 'query'
     #   * time (recommended) the integer time in milliseconds
+    #   * page_load_time (optional)
+    #   * dns_time (optional)
+    #   * page_download_time (optional)
+    #   * redirect_response_time (optional)
+    #   * tcp_connect_time (optional)
+    #   * server_response_time (optional) most useful on the server-side
     # @param block [#call] if a block is provided, the time it takes to
-    #   run will be recorded and set as the `time` value option
+    #   run will be recorded and set as the `time` value option, no other
+    #   time values will be set.
     # @return [<Net::HTTPOK] the GA `/collect` endpoint always returns a 200
     def timing(options = {}, &block)
       Staccato::Timing.new(self, options).track!(&block)
@@ -101,6 +112,10 @@ module Staccato
     # (see Tracker#initialize)
     def initialize(*); end
 
+    def hit_defaults
+      {}
+    end
+
     # (see Tracker#id)
     def id
       nil

data/lib/staccato/transaction_item.rb

@@ -10,6 +10,7 @@ module Staccato
       quantity: 'iq',
       code: 'ic',
       variation: 'iv',
+      category: 'iv', # duplicates 'variation'
       currency: 'cu'
     }
 

data/lib/staccato/version.rb

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

data/spec/integration/tracker_spec.rb

@@ -215,4 +215,23 @@ describe Staccato::Tracker do
       end
     end
   end
+
+  context "with defaults" do
+    before(:each) do
+      tracker.hit_defaults[:document_hostname] = 'mysite.com'
+    end
+
+    it 'tracks page path and default hostname' do
+      tracker.pageview(path: '/foobar')
+
+      Net::HTTP.should have_received(:post_form).with(uri, {
+        'v' => 1,
+        'tid' => 'UA-XXXX-Y',
+        'cid' => '555',
+        't' => 'pageview',
+        'dh' => 'mysite.com',
+        'dp' => '/foobar'
+      })
+    end
+  end
 end

data/spec/lib/staccato/exception_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe Staccato::Exception do
+  let(:tracker) { Staccato::NoopTracker.new }
+
+  it 'converts false fatal boolean field values to 0' do
+    expect(Staccato::Exception.new(tracker, fatal: false).params['exf']).to eq(0)
+  end
+
+  it 'does not convert fatal field integer values' do
+    expect(Staccato::Exception.new(tracker, fatal: 0).params['exf']).to eq(0)
+  end
+
+  it 'converts true fatal boolean field values to 1' do
+    expect(Staccato::Exception.new(tracker, fatal: true).params['exf']).to eq(1)
+  end
+
+  it 'rejects nil fatal boolean field values' do
+    expect(Staccato::Exception.new(tracker, fatal: nil).params.has_key?('exf')).to be_false
+  end
+end

data/spec/lib/staccato/hit_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+class EmptyHit
+  FIELDS = {}
+
+  include Staccato::Hit
+
+  def type; :empty; end
+end
+
+describe Staccato::Hit do
+  let(:hit_klass) { EmptyHit }
+  let(:tracker) { Staccato::NoopTracker.new }
+
+  it 'converts false boolean field values to 0' do
+    expect(hit_klass.new(tracker, anonymize_ip: false).params['aip']).to eq(0)
+  end
+
+  it 'does not convert integer values in boolean fields' do
+    expect(hit_klass.new(tracker, non_interactive: 0).params['ni']).to eq(0)
+  end
+
+  it 'converts true boolean field values to 1' do
+    expect(hit_klass.new(tracker, java_enabled: true).params['je']).to eq(1)
+  end
+
+  it 'rejects nil boolean field values' do
+    expect(hit_klass.new(tracker, non_interactive: nil).params.has_key?('ni')).to be_false
+  end
+end

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: staccato
 version: !ruby/object:Gem::Version
-  version: 0.0.4
-  prerelease: 
+  version: 0.1.0
 platform: ruby
 authors:
 - Tony Pitale
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-24 00:00:00.000000000 Z
+date: 2014-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -46,7 +41,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -54,7 +48,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -62,7 +55,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -70,7 +62,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -78,7 +69,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: bourne
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -86,7 +76,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -94,7 +83,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -102,7 +90,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -139,6 +126,8 @@ files:
 - spec/integration/tracker_spec.rb
 - spec/lib/stacatto_spec.rb
 - spec/lib/staccato/event_spec.rb
+- spec/lib/staccato/exception_spec.rb
+- spec/lib/staccato/hit_spec.rb
 - spec/lib/staccato/pageview_spec.rb
 - spec/lib/staccato/tracker_spec.rb
 - spec/spec_helper.rb
@@ -146,33 +135,34 @@ files:
 homepage: https://github.com/tpitale/staccato
 licenses:
 - MIT
+metadata: {}
 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.8.23
+rubygems_version: 2.2.1
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Ruby Google Analytics Measurement
 test_files:
 - spec/integration/noop_tracker_spec.rb
 - spec/integration/tracker_spec.rb
 - spec/lib/stacatto_spec.rb
 - spec/lib/staccato/event_spec.rb
+- spec/lib/staccato/exception_spec.rb
+- spec/lib/staccato/hit_spec.rb
 - spec/lib/staccato/pageview_spec.rb
 - spec/lib/staccato/tracker_spec.rb
 - spec/spec_helper.rb