Class: Gabba::Gabba

Inherits:
Object
  • Object
show all
Defined in:
lib/gabba/gabba.rb

Constant Summary collapse

GOOGLE_HOST = 
"www.google-analytics.com"
BEACON_PATH = 
"/__utm.gif"
USER_AGENT = 
"Gabba #{VERSION} Agent"
VISITOR =

Custom var levels

1
SESSION = 
2
PAGE = 
3
ESCAPES = 
%w{ ' ! * ) }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ga_acct, domain, agent = Gabba::USER_AGENT) ⇒ Gabba

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")



38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/gabba/gabba.rb', line 38

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

Instance Attribute Details

#user_agent ⇒ Object

Returns the value of attribute user_agent.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def user_agent
  @user_agent
end

#utmac ⇒ Object

Returns the value of attribute utmac.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmac
  @utmac
end

#utmcc ⇒ Object

Returns the value of attribute utmcc.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmcc
  @utmcc
end

#utmcs ⇒ Object

Returns the value of attribute utmcs.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmcs
  @utmcs
end

#utmdt ⇒ Object

Returns the value of attribute utmdt.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmdt
  @utmdt
end

#utmhn ⇒ Object

Returns the value of attribute utmhn.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmhn
  @utmhn
end

#utmn ⇒ Object

Returns the value of attribute utmn.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmn
  @utmn
end

#utmp ⇒ Object

Returns the value of attribute utmp.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmp
  @utmp
end

#utmt ⇒ Object

Returns the value of attribute utmt.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmt
  @utmt
end

#utmul ⇒ Object

Returns the value of attribute utmul.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmul
  @utmul
end

#utmwv ⇒ Object

Returns the value of attribute utmwv.



25
26
27
 
# File 'lib/gabba/gabba.rb', line 25

def utmwv
  @utmwv
end

Instance Method Details

#add_item(order_id, item_sku, price, quantity, name = nil, category = nil, utmhid = random_id) ⇒ Object

Public: Track an item purchased in an ecommerce transaction to Google Analytics. (code.google.com/apis/analytics/docs/gaJS/gaJSApiEcommerce.html#gat.GA_Tracker._addItem)



249
250
251
252
 
# File 'lib/gabba/gabba.rb', line 249

def add_item(order_id, item_sku, price, quantity, name = nil, category = nil, utmhid = random_id)
  
  hey(item_params(order_id, item_sku, name, category, price, quantity, utmhid))
end

#check_account_params ⇒ Object

sanity check that we have needed params to even call GA

Raises:



304
305
306
307
 
# File 'lib/gabba/gabba.rb', line 304

def 
  raise NoGoogleAnalyticsAccountError unless @utmac
  raise NoGoogleAnalyticsDomainError unless @utmhn
end

#cookie_params(utma1 = random_id, utma2 = rand(1147483647) + 1000000000, today = Time.now) ⇒ Object

create magical cookie params used by GA for its own nefarious purposes



297
298
299
300
301
 
# File 'lib/gabba/gabba.rb', line 297

def cookie_params(utma1 = random_id, utma2 = rand(1147483647) + 1000000000, today = Time.now)
  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

#custom_var_data ⇒ Object

Public: Renders the custom variable data in the format needed for GA (code.google.com/apis/analytics/docs/tracking/gaTrackingCustomVariables.html) Called before actually sending the data along to GA.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/gabba/gabba.rb', line 93

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)
    prefix = "#{i}!" if idx != i
    names  << "#{prefix}#{escape(n)}"
    values << "#{prefix}#{escape(v)}"
    scopes << "#{prefix}#{escape(s)}"
    idx = i + 1
  end

  names.empty? ? "" : "8(#{names.join('*')})9(#{values.join('*')})11(#{scopes.join('*')})"
end

#delete_custom_var(index) ⇒ Object

Public: Delete a previously set custom variable so if is not passed along and logged by Google Analytics (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)



84
85
86
87
88
 
# File 'lib/gabba/gabba.rb', line 84

def delete_custom_var(index)
  raise "Index must be between 1 and 5" unless (1..5).include?(index)

  @custom_vars.delete_at(index)
end

#escape(t) ⇒ Object 



328
329
330
331
332
333
334
 
# File 'lib/gabba/gabba.rb', line 328

def escape(t)
  return t if !t || (/\w/ !~ t.to_s)

  t.to_s.gsub(/[\*'!\)]/) do |m|
    "'#{ESCAPES.index(m)}"
  end
end

#event(category, action, label = nil, value = nil, utmni = false, utmhid = random_id) ⇒ Object

Public: Record an event in Google Analytics (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)



165
166
167
168
 
# File 'lib/gabba/gabba.rb', line 165

def event(category, action, label = nil, value = nil, utmni = false, utmhid = random_id)
  
  hey(event_params(category, action, label, value, utmni, utmhid))
end

#event_data(category, action, label = nil, value = nil) ⇒ Object

Public: Renders event individual param data in the format needed for GA Called before actually sending the data along to GA in Gabba#event



191
192
193
194
195
 
# File 'lib/gabba/gabba.rb', line 191

def event_data(category, action, label = nil, value = nil)
  data = "5(#{category}*#{action}" + (label ? "*#{label})" : ")")
  data += "(#{value})" if value
  data
end

#event_params(category, action, label = nil, value = nil, utmni = false, utmhid = false) ⇒ Object

Public: Renders event params data in the format needed for GA Called before actually sending the data along to GA in Gabba#event

Raises:

  • (ArgumentError) 


172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/gabba/gabba.rb', line 172

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)
  {
    :utmwv => @utmwv,
    :utmn => @utmn,
    :utmhn => @utmhn,
    :utmni => (1 if utmni), # 1 for non interactive event, excluded from bounce calcs
    :utmt => 'event',
    :utme => "#{event_data(category, action, label, value)}#{custom_var_data}",
    :utmcs => @utmcs,
    :utmul => @utmul,
    :utmhid => utmhid,
    :utmac => @utmac,
    :utmcc => @utmcc || cookie_params
  }
end

#hey(params) ⇒ Object

makes the tracking call to Google Analytics

Raises:



310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/gabba/gabba.rb', line 310

def hey(params)
  query = params.map {|k,v| "#{k}=#{URI.escape(v.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))}" }.join('&')

  response = Net::HTTP.start(GOOGLE_HOST) do |http|
    request = Net::HTTP::Get.new("#{BEACON_PATH}?#{query}")
    request["User-Agent"] = URI.escape(user_agent)
    request["Accept"] = "*/*"
    http.request(request)
  end

  raise GoogleAnalyticsNetworkError unless response.code == "200"
  response
end

#identify_user(utma) ⇒ Object

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")



292
293
294
 
# File 'lib/gabba/gabba.rb', line 292

def identify_user(utma)
  @utma = utma
end

#item_params(order_id, item_sku, name, category, price, quantity, utmhid) ⇒ Object

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



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/gabba/gabba.rb', line 256

def item_params(order_id, item_sku, name, category, price, quantity, utmhid)
  # '1234',           // utmtid URL-encoded order ID - required
  # 'DD44',           // utmipc SKU/code - required
  # 'T-Shirt',        // utmipn product name
  # 'Green Medium',   // utmiva category or variation
  # '11.99',          // utmipr unit price - required
  # '1'               // utmiqt quantity - required
  {
    :utmwv => @utmwv,
    :utmn => @utmn,
    :utmhn => @utmhn,
    :utmt => 'item',
    :utmcs => @utmcs,
    :utmul => @utmul,
    :utmhid => utmhid,
    :utmac => @utmac,
    :utmcc => @utmcc || cookie_params,
    :utmtid => order_id,
    :utmipc => item_sku,
    :utmipn => name,
    :utmiva => category,
    :utmipr => price,
    :utmiqt => quantity
  }
end

#page_view(title, page, utmhid = random_id) ⇒ Object

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")



122
123
124
125
 
# File 'lib/gabba/gabba.rb', line 122

def page_view(title, page, utmhid = random_id)
  
  hey(page_view_params(title, page, utmhid))
end

#page_view_params(title, page, utmhid = random_id) ⇒ Object

Public: Renders the page view params data in the format needed for GA Called before actually sending the data along to GA.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/gabba/gabba.rb', line 129

def page_view_params(title, page, utmhid = random_id)
  options = {
    :utmwv => @utmwv,
    :utmn => @utmn,
    :utmhn => @utmhn,
    :utmcs => @utmcs,
    :utmul => @utmul,
    :utmdt => title,
    :utmhid => utmhid,
    :utmp => page,
    :utmac => @utmac,
    :utmcc => @utmcc || cookie_params
  }

  # Add custom vars if present
  cvd = custom_var_data
  options[:utme] = cvd if /\w/ =~ cvd

  options
end

#random_id ⇒ Object 



324
325
326
 
# File 'lib/gabba/gabba.rb', line 324

def random_id
  rand 8999999999 + 1000000000
end

#set_custom_var(index, name, value, scope) ⇒ Object

Public: Set a custom variable to be passed along and logged by Google Analytics (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



68
69
70
71
72
73
 
# File 'lib/gabba/gabba.rb', line 68

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

#transaction(order_id, total, store_name = nil, tax = nil, shipping = nil, city = nil, region = nil, country = nil, utmhid = random_id) ⇒ Object

Public: Track an entire ecommerce transaction to Google Analytics in one call. (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')



218
219
220
221
 
# File 'lib/gabba/gabba.rb', line 218

def transaction(order_id, total, store_name = nil, tax = nil, shipping = nil, city = nil, region = nil, country = nil, utmhid = random_id)
  
  hey(transaction_params(order_id, total, store_name, tax, shipping, city, region, country, utmhid))
end

#transaction_params(order_id, total, store_name, tax, shipping, city, region, country, utmhid) ⇒ Object

Public: Renders transaction params data in the format needed for GA Called before actually sending the data along to GA in Gabba#transaction



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/gabba/gabba.rb', line 225

def transaction_params(order_id, total, store_name, tax, shipping, city, region, country, utmhid)
  {
    :utmwv => @utmwv,
    :utmn => @utmn,
    :utmhn => @utmhn,
    :utmt => 'tran',
    :utmcs => @utmcs,
    :utmul => @utmul,
    :utmhid => utmhid,
    :utmac => @utmac,
    :utmcc => @utmcc || cookie_params,
    :utmtid => order_id,
    :utmtst => store_name,
    :utmtto => total,
    :utmttx => tax,
    :utmtsp => shipping,
    :utmtci => city,
    :utmtrg => region,
    :utmtco => country
  }
end