gabba 0.2.0 → 0.3.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gabba (0.1.1)
+    gabba (0.2.0)
 
 GEM
   remote: http://rubygems.org/

data/README

@@ -14,20 +14,30 @@ HOW TO USE:
 
         Gabba::Gabba.new("UT-1234", "mydomain.com").event("Videos", "Play", "ID", "123", true)
 
+* Works with existing client-side Google Analytics cookies
+
+        gabba = Gabba::Gabba.new("UT-1234", "mydomain.com")
+
+        # grab the __utma unique identifier
+        gabba.identify_user(cookies[:__utma])
+
+        # trigger actions as normal
+        gabba.page_view("something", "track/me")
+
 * Setting custom vars
 
         # Index: 1 through 5
         index = 1
-        
+
         # Scope: VISITOR, SESSION or PAGE
         scope = Gabba::Gabba::VISITOR
-        
+
         # Set var
         gabba.set_custom_var(index, 'Name', 'Value', scope)
-        
+
         # Track the event (all vars will be included)
         gabba.event(...)
-        
+
         # Track the page view (all vars will be included)
         gabba.page_view(...)
 
@@ -39,3 +49,8 @@ HOW TO USE:
         # Delete var with this index
         gabba.delete_custom_var index- Track a non-interactive custom event
 
+* Track ecommerce transactions
+
+        g = Gabba::Gabba.new("UT-6666", "myawesomeshop.net")
+        g.transaction("123456789", "1000.00", 'Acme Clothing', '1.29', '5.00', 'Los Angeles', 'California', 'USA')
+

data/lib/gabba/gabba.rb

@@ -5,11 +5,11 @@ require 'cgi'
 require File.dirname(__FILE__) + '/version'
 
 module Gabba
-  
+
   class NoGoogleAnalyticsAccountError < RuntimeError; end
   class NoGoogleAnalyticsDomainError < RuntimeError; end
   class GoogleAnalyticsNetworkError < RuntimeError; end
-  
+
   class Gabba
     GOOGLE_HOST = "www.google-analytics.com"
     BEACON_PATH = "/__utm.gif"
@@ -21,42 +21,80 @@ module Gabba
     PAGE    = 3
 
     ESCAPES = %w{ ' ! * ) }
-    
+
     attr_accessor :utmwv, :utmn, :utmhn, :utmcs, :utmul, :utmdt, :utmp, :utmac, :utmt, :utmcc, :user_agent
-    
+
+    # Public: Initialize Gabba Google Analytics Tracking Object.
+    #
+    # ga_acct - A String containing your Google Analytics account id.
+    # domain  - A String containing which domain you want the tracking data to be logged from.
+    # agent   - A String containing the user agent you want the tracking to appear to be coming from.
+    #           Defaults to "Gabba 0.2 Agent" or whatever the corrent version is.
+    #
+    # Example:
+    #
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #
     def initialize(ga_acct, domain, agent = Gabba::USER_AGENT)
       @utmwv = "4.4sh" # GA version
       @utmcs = "UTF-8" # charset
       @utmul = "en-us" # language
-       
+
       @utmn = random_id
       @utmhid = random_id
-      
+
       @utmac = ga_acct
       @utmhn = domain
       @user_agent = agent
 
       @custom_vars = []
     end
-  
+
+    # Public: Set a custom variable to be passed along and logged by Google Analytics
+    # (http://code.google.com/apis/analytics/docs/tracking/gaTrackingCustomVariables.html)
+    #
+    # index  - Integer between 1 and 5 for this custom variable
+    # name   - String with the name of the custom variable
+    # value  - String with the value for teh custom variable
+    # scope  - Integer with custom variable scope must be 1 (VISITOR), 2 (SESSION) or 3 (PAGE)
+    #
+    # Example:
+    #
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #   g.set_custom_var(1, 'awesomeness', 'supreme', Gabba::VISITOR)
+    #   # => ['awesomeness', 'supreme', 1]
+    #
+    # Returns array with the custom variable data
     def set_custom_var(index, name, value, scope)
       raise "Index must be between 1 and 5" unless (1..5).include?(index)
       raise "Scope must be 1 (VISITOR), 2 (SESSION) or 3 (PAGE)" unless (1..3).include?(scope)
-      
+
       @custom_vars[index] = [ name, value, scope ]
     end
-    
+
+    # Public: Delete a previously set custom variable so if is not passed along and logged by Google Analytics
+    # (http://code.google.com/apis/analytics/docs/tracking/gaTrackingCustomVariables.html)
+    #
+    # index  - Integer between 1 and 5 for this custom variable
+    #
+    # Example:
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #   g.delete_custom_var(1)
+    #
     def delete_custom_var(index)
       raise "Index must be between 1 and 5" unless (1..5).include?(index)
 
       @custom_vars.delete_at(index)
     end
-    
+
+    # Public: Renders the custom variable data in the format needed for GA
+    # (http://code.google.com/apis/analytics/docs/tracking/gaTrackingCustomVariables.html)
+    # Called before actually sending the data along to GA.
     def custom_var_data
       names  = []
       values = []
       scopes = []
-      
+
       idx = 1
       @custom_vars.each_with_index do |(n, v, s), i|
         next if !n || !v || (/\w/ !~ n) || (/\w/ !~ v)
@@ -66,15 +104,28 @@ module Gabba
         scopes << "#{prefix}#{escape(s)}"
         idx = i + 1
       end
-      
+
       names.empty? ? "" : "8(#{names.join('*')})9(#{values.join('*')})11(#{scopes.join('*')})"
     end
-    
+
+    # Public: Record a page view in Google Analytics
+    #
+    # title   - String with the page title for thr page view
+    # page    - String with the path for the page view
+    # utmhid  - String with the unique visitor id, defaults to a new random value
+    #
+    # Example:
+    #
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #   g.page_view("something", "track/me")
+    #
     def page_view(title, page, utmhid = random_id)
       check_account_params
       hey(page_view_params(title, page, utmhid))
     end
 
+    # Public: Renders the page view params data in the format needed for GA
+    # Called before actually sending the data along to GA.
     def page_view_params(title, page, utmhid = random_id)
       options = {
         :utmwv => @utmwv,
@@ -95,12 +146,29 @@ module Gabba
 
       options
     end
-  
+
+    # Public: Record an event in Google Analytics
+    # (http://code.google.com/apis/analytics/docs/gaJS/gaJSApiEventTracking.html)
+    #
+    # category  -
+    # action    -
+    # label     -
+    # value     -
+    # utmni     -
+    # utmhid    -
+    #
+    # Example:
+    #
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #   g.event("Videos", "Play", "ID", "123", true)
+    #
     def event(category, action, label = nil, value = nil, utmni = false, utmhid = random_id)
       check_account_params
       hey(event_params(category, action, label, value, utmni, utmhid))
     end
 
+    # Public: Renders event params data in the format needed for GA
+    # Called before actually sending the data along to GA in Gabba#event
     def event_params(category, action, label = nil, value = nil, utmni = false, utmhid = false)
       raise ArgumentError.new("utmni must be a boolean") if (utmni.class != TrueClass && utmni.class != FalseClass)
       {
@@ -118,26 +186,43 @@ module Gabba
       }
     end
 
+    # Public: Renders event individual param data in the format needed for GA
+    # Called before actually sending the data along to GA in Gabba#event
     def event_data(category, action, label = nil, value = nil)
       data = "5(#{category}*#{action}" + (label ? "*#{label})" : ")")
       data += "(#{value})" if value
       data
     end
-    
+
+    # Public:  Track an entire ecommerce transaction to Google Analytics in one call.
+    # (http://code.google.com/apis/analytics/docs/gaJS/gaJSApiEcommerce.html#_gat.GA_Tracker_._trackTrans)
+    #
+    # order_id    - URL-encoded order ID (required). Maps to utmtid
+    # total       - Order total (required). Maps to utmtto
+    # store_name  - Affiliation or store name (default: nil). Maps to utmtst
+    # tax         - Sales tax (default: nil). Maps to utmttx
+    # shipping    - Shipping (default: nil). Maps to utmtsp
+    # city        - City (default: nil). Maps to utmtci
+    # region      - State or Provance (default: nil). Maps to utmtrg
+    # country     - Country (default: nil). Maps to utmtco
+    # utmhid      - String with the unique visitor id (default: random_id)
+    #
+    # Examples:
+    #
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #   g.transaction("123456789", "1000.00")
+    #
+    #   g = Gabba::Gabba.new("UT-6666", "myawesomeshop.net")
+    #   g.transaction("123456789", "1000.00", 'Acme Clothing', '1.29', '5.00', 'Los Angeles', 'California', 'USA')
+    #
     def transaction(order_id, total, store_name = nil, tax = nil, shipping = nil, city = nil, region = nil, country = nil, utmhid = random_id)
       check_account_params
       hey(transaction_params(order_id, total, store_name, tax, shipping, city, region, country, utmhid))
     end
 
+    # Public: Renders transaction params data in the format needed for GA
+    # Called before actually sending the data along to GA in Gabba#transaction
     def transaction_params(order_id, total, store_name, tax, shipping, city, region, country, utmhid)
-      # '1234',           // utmtid URL-encoded order ID - required
-      # 'Acme Clothing',  // utmtst affiliation or store name
-      # '11.99',          // utmtto total - required
-      # '1.29',           // utmttx tax
-      # '5',              // utmtsp shipping
-      # 'San Jose',       // utmtci city
-      # 'California',     // utmtrg state or province
-      # 'USA'             // utmtco country
       {
         :utmwv => @utmwv,
         :utmn => @utmn,
@@ -158,12 +243,16 @@ module Gabba
         :utmtco => country
       }
     end
-    
+
+    # Public:  Track an item purchased in an ecommerce transaction to Google Analytics.
+    # (http://code.google.com/apis/analytics/docs/gaJS/gaJSApiEcommerce.html#_gat.GA_Tracker_._addItem)
     def add_item(order_id, item_sku, price, quantity, name = nil, category = nil, utmhid = random_id)
       check_account_params
       hey(item_params(order_id, item_sku, name, category, price, quantity, utmhid))
     end
-    
+
+    # Public: Renders item purchase params data in the format needed for GA
+    # Called before actually sending the data along to GA in Gabba#add_item
     def item_params(order_id, item_sku, name, category, price, quantity, utmhid)
       # '1234',           // utmtid URL-encoded order ID - required
       # 'DD44',           // utmipc SKU/code - required
@@ -189,10 +278,26 @@ module Gabba
         :utmiqt => quantity
       }
     end
-  
+
+    # Public: provide the user's __utma attribute from analytics cookie, allowing
+    # better tracking of user flows
+    #
+    # Called before page_view etc
+    #
+    # Examples:
+    #   g = Gabba::Gabba.new("UT-1234", "mydomain.com")
+    #   g.identify_user(cookies[:__utma])
+    #   g.page_view("something", "track/me")
+    #
+    def identify_user(utma)
+      @utma = utma
+    end
+
     # create magical cookie params used by GA for its own nefarious purposes
     def cookie_params(utma1 = random_id, utma2 = rand(1147483647) + 1000000000, today = Time.now)
-      "__utma=1.#{utma1}00145214523.#{utma2}.#{today.to_i}.#{today.to_i}.15;+__utmz=1.#{today.to_i}.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none);"
+      utma = @utma
+      utma ||= "1.#{utma1}00145214523.#{utma2}.#{today.to_i}.#{today.to_i}.15"
+      "__utma=#{utma};+__utmz=1.#{today.to_i}.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none);"
     end
 
     # sanity check that we have needed params to even call GA
@@ -219,15 +324,15 @@ module Gabba
     def random_id
       rand 8999999999 + 1000000000
     end
-        
+
     def escape(t)
       return t if !t || (/\w/ !~ t.to_s)
-      
+
       t.to_s.gsub(/[\*'!\)]/) do |m|
-        "'#{ESCAPES.index(m)}" 
+        "'#{ESCAPES.index(m)}"
       end
     end
-    
+
   end # Gabba Class
 
 end

data/lib/gabba/version.rb

@@ -1,5 +1,5 @@
 module Gabba
   unless const_defined?('VERSION')
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/spec/gabba_spec.rb

@@ -1,7 +1,7 @@
-require File.dirname(__FILE__) + '/spec_helper'
+require File.expand_path(File.dirname(__FILE__) + "/spec_helper")
 
 describe Gabba::Gabba do
-  
+
   describe "when tracking page views" do
     before do
       @gabba = Gabba::Gabba.new("abc", "123")
@@ -9,7 +9,7 @@ describe Gabba::Gabba do
       @gabba.utmcc = ''
       stub_analytics @gabba.page_view_params("title", "/page/path", "6783939397")
     end
-    
+
     it "must require GA account" do
       lambda {Gabba::Gabba.new(nil, nil).page_view("thing", "thing")}.must_raise(Gabba::NoGoogleAnalyticsAccountError)
     end
@@ -17,7 +17,7 @@ describe Gabba::Gabba do
     it "must require GA domain" do
       lambda {Gabba::Gabba.new("abs", nil).page_view("thing", "thing")}.must_raise(Gabba::NoGoogleAnalyticsDomainError)
     end
-    
+
     it "must be able to create page_view_params" do
       @gabba.page_view_params("hiya", "/tracker/page")[:utmdt].must_equal("hiya")
     end
@@ -34,7 +34,7 @@ describe Gabba::Gabba do
       @gabba.utmcc = ''
       stub_analytics @gabba.event_params("cat1", "act1", "lab1", "val1", false, "6783939397")
     end
-    
+
     it "must require GA account" do
       lambda {Gabba::Gabba.new(nil, nil).event("cat1", "act1", "lab1", "val1")}.must_raise(Gabba::NoGoogleAnalyticsAccountError)
     end
@@ -42,7 +42,7 @@ describe Gabba::Gabba do
     it "must require GA domain" do
       lambda {Gabba::Gabba.new("abs", nil).event("cat1", "act1", "lab1", "val1")}.must_raise(Gabba::NoGoogleAnalyticsDomainError)
     end
-    
+
     it "must be able to create event data" do
       @gabba.event_data("cat1", "act1", "lab1", "val1").must_equal("5(cat1*act1*lab1)(val1)")
     end
@@ -50,7 +50,7 @@ describe Gabba::Gabba do
     it "must be able to create event data with only category and action" do
       @gabba.event_data("cat1", "act1").must_equal("5(cat1*act1)")
     end
-    
+
     it "must do event request to google" do
       @gabba.event("cat1", "act1", "lab1", "val1", false, "6783939397").code.must_equal("200")
     end
@@ -60,7 +60,7 @@ describe Gabba::Gabba do
     end
 
   end
-  
+
   describe "when tracking an item" do
     before do
       @gabba = Gabba::Gabba.new("abc", "123")
@@ -68,7 +68,7 @@ describe Gabba::Gabba do
       @gabba.utmcc = ''
       stub_analytics @gabba.item_params("orderid", "1234", "widget", "widgets", "9.99", "1", "6783939397")
     end
-    
+
     it "must require GA account" do
       lambda {Gabba::Gabba.new(nil, nil).add_item("orderid", "1234", "widget", "widgets", "9.99", "1", "6783939397")}.must_raise(Gabba::NoGoogleAnalyticsAccountError)
     end
@@ -76,12 +76,12 @@ describe Gabba::Gabba do
     it "must require GA domain" do
       lambda {Gabba::Gabba.new("abs", nil).add_item("orderid", "1234", "widget", "widgets", "9.99", "1", "6783939397")}.must_raise(Gabba::NoGoogleAnalyticsDomainError)
     end
-    
+
     it "must do add item request to google" do
       @gabba.add_item("orderid", "1234", "widget", "widgets", "9.99", "1", "6783939397").code.must_equal("200")
     end
   end
-  
+
   describe "when tracking a transaction" do
     before do
       @gabba = Gabba::Gabba.new("abc", "123")
@@ -89,7 +89,7 @@ describe Gabba::Gabba do
       @gabba.utmcc = ''
       stub_analytics @gabba.transaction_params("orderid", "9.99", "acme stores", ".25", "1.00", "San Jose", "CA", "United States", "6783939397")
     end
-    
+
     it "must require GA account" do
       lambda {Gabba::Gabba.new(nil, nil).transaction("orderid", "9.99", "acme stores", ".25", "1.00", "San Jose", "CA", "United States", "6783939397")}.must_raise(Gabba::NoGoogleAnalyticsAccountError)
     end
@@ -97,34 +97,48 @@ describe Gabba::Gabba do
     it "must require GA domain" do
       lambda {Gabba::Gabba.new("abs", nil).transaction("orderid", "9.99", "acme stores", ".25", "1.00", "San Jose", "CA", "United States", "6783939397")}.must_raise(Gabba::NoGoogleAnalyticsDomainError)
     end
-    
+
     it "must do transaction request to google" do
       @gabba.transaction("orderid", "9.99", "acme stores", ".25", "1.00", "San Jose", "CA", "United States", "6783939397").code.must_equal("200")
     end
   end
 
+  describe "when using identify_user" do
+    before do
+      @gabba = Gabba::Gabba.new("abc", "123")
+      @gabba.utmn = "1009731272"
+      @gabba.utmcc = ''
+    end
+    it "must use the supplied utma in cookie_params" do
+      # This is how the Google cookie is named
+      cookies = { :__utma => "long_code"}
+      @gabba.identify_user(cookies[:__utma])
+      @gabba.cookie_params.must_match /utma=long_code;/
+    end
+  end
+
   describe "setting a custom var" do
     before do
       @gabba = Gabba::Gabba.new("abc", "123")
       @gabba.utmn = "1009731272"
       @gabba.utmcc = ''
     end
-    
+
     it "must return data for a valid var" do
       @gabba.set_custom_var 1, 'A (B*\'!)', 'Yes', Gabba::Gabba::SESSION
       @gabba.custom_var_data.must_equal "8(A (B'2'0'1'3)9(Yes)11(2)"
     end
-    
+
     it "must return data for several valid vards" do
       @gabba.set_custom_var 1, 'A', 'Yes', Gabba::Gabba::SESSION
       @gabba.set_custom_var 2, 'B', 'No', Gabba::Gabba::VISITOR
       @gabba.custom_var_data.must_equal "8(A*B)9(Yes*No)11(2*1)"
     end
-    
+
     it "must return an empty string if vars aren't set" do
       @gabba.custom_var_data.must_equal ""
     end
-    
+
     it "must not include var with an empty value" do
       @gabba.set_custom_var 1, 'A', 'Yes', Gabba::Gabba::SESSION
       @gabba.set_custom_var 2, 'B', '',    Gabba::Gabba::VISITOR
@@ -132,18 +146,18 @@ describe Gabba::Gabba do
       @gabba.set_custom_var 4, 'D', nil,   Gabba::Gabba::VISITOR
       @gabba.custom_var_data.must_equal "8(A)9(Yes)11(2)"
     end
-    
+
     it "must mention index of the var if non sequential" do
       @gabba.set_custom_var 2, 'A', 'Y', Gabba::Gabba::SESSION
       @gabba.set_custom_var 4, 'D', 'N', Gabba::Gabba::VISITOR
       @gabba.custom_var_data.must_equal "8(2!A*4!D)9(2!Y*4!N)11(2!2*4!1)"
     end
-    
+
     it "must raise an error if index is outside the 1-5 (incl) range" do
       lambda { @gabba.set_custom_var(0, 'A', 'B', 1) }.must_raise(RuntimeError)
       lambda { @gabba.set_custom_var(6, 'A', 'B', 1) }.must_raise(RuntimeError)
     end
-    
+
     it "must raise an error if scope is outside the 1-3 (incl) range" do
       lambda { @gabba.set_custom_var(1, 'A', 'B', 0) }.must_raise(RuntimeError)
       lambda { @gabba.set_custom_var(1, 'A', 'B', 4) }.must_raise(RuntimeError)
@@ -156,14 +170,14 @@ describe Gabba::Gabba do
       @gabba.utmn = "1009731272"
       @gabba.utmcc = ''
     end
-    
+
     it "must return data for a valid var" do
       @gabba.set_custom_var 1, 'A (B*\'!)', 'Yes', Gabba::Gabba::SESSION
       @gabba.delete_custom_var 1
       @gabba.custom_var_data.must_equal ""
     end
   end
-  
+
   def stub_analytics(expected_params)
     s = stub_request(:get, /www.google-analytics.com\/__utm.gif\?utmac=#{expected_params[:utmac]}&.*/).
           to_return(:status => 200, :body => "", :headers => {})

metadata

@@ -1,33 +1,23 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: gabba
-version: !ruby/object:Gem::Version 
-  hash: 23
+version: !ruby/object:Gem::Version
+  version: 0.3.0
   prerelease: 
-  segments: 
-  - 0
-  - 2
-  - 0
-  version: 0.2.0
 platform: ruby
-authors: 
+authors:
 - Ron Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-03-23 00:00:00 Z
+date: 2012-04-02 00:00:00.000000000Z
 dependencies: []
-
 description: Easy server-side tracking for Google Analytics
-email: 
+email:
 - ron dot evans at gmail dot com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - Gemfile.lock
@@ -39,39 +29,30 @@ files:
 - lib/gabba/version.rb
 - spec/gabba_spec.rb
 - spec/spec_helper.rb
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: gabba
 rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: Easy server-side tracking for Google Analytics
-test_files: 
+test_files:
 - spec/gabba_spec.rb
 - spec/spec_helper.rb