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



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

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 && agent.length > 0) ? agent : Gabba::USER_AGENT

  @custom_vars = []
end

Instance Attribute Details

#user_agent ⇒ Object

Returns the value of attribute user_agent.



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

def user_agent
  @user_agent
end

#utma ⇒ Object

Returns the value of attribute utma.



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

def utma
  @utma
end

#utmac ⇒ Object

Returns the value of attribute utmac.



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

def utmac
  @utmac
end

#utmcc ⇒ Object

Returns the value of attribute utmcc.



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

def utmcc
  @utmcc
end

#utmcs ⇒ Object

Returns the value of attribute utmcs.



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

def utmcs
  @utmcs
end

#utmdt ⇒ Object

Returns the value of attribute utmdt.



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

def utmdt
  @utmdt
end

#utmhn ⇒ Object

Returns the value of attribute utmhn.



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

def utmhn
  @utmhn
end

#utmip ⇒ Object

Returns the value of attribute utmip.



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

def utmip
  @utmip
end

#utmn ⇒ Object

Returns the value of attribute utmn.



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

def utmn
  @utmn
end

#utmp ⇒ Object

Returns the value of attribute utmp.



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

def utmp
  @utmp
end

#utmr ⇒ Object

Returns the value of attribute utmr.



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

def utmr
  @utmr
end

#utmt ⇒ Object

Returns the value of attribute utmt.



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

def utmt
  @utmt
end

#utmul ⇒ Object

Returns the value of attribute utmul.



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

def utmul
  @utmul
end

#utmwv ⇒ Object

Returns the value of attribute utmwv.



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

def utmwv
  @utmwv
end

#utmz ⇒ Object

Returns the value of attribute utmz.



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

def utmz
  @utmz
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)



256
257
258
259
 
# File 'lib/gabba/gabba.rb', line 256

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:



343
344
345
346
 
# File 'lib/gabba/gabba.rb', line 343

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



336
337
338
339
340
 
# File 'lib/gabba/gabba.rb', line 336

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};+__utmz=#{@utmz};"
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.



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

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)



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

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 



367
368
369
370
371
372
373
 
# File 'lib/gabba/gabba.rb', line 367

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)



168
169
170
171
 
# File 'lib/gabba/gabba.rb', line 168

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



196
197
198
199
200
 
# File 'lib/gabba/gabba.rb', line 196

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) 


175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/gabba/gabba.rb', line 175

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,
    :utmr => @utmr,
    :utmip => @utmip
  }
end

#hey(params) ⇒ Object

makes the tracking call to Google Analytics

Raises:



349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/gabba/gabba.rb', line 349

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, utmz = nil) ⇒ Object

Public: provide the user’s __utma and __utmz attributes 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], cookies[:__utmz])
g.page_view("something", "track/me")



301
302
303
304
305
 
# File 'lib/gabba/gabba.rb', line 301

def identify_user(utma, utmz=nil)
  @utma = utma
  @utmz = utmz
  self
end

#ip(utmip) ⇒ Object

Public: provide the utmip attribute, allowing for IP address tracking

Called before page_view etc

Examples:

g = Gabba::Gabba.new("UT-1234", "mydomain.com")
g.ip(request.env["REMOTE_ADDR"])
g.page_view("something", "track/me")



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

def ip(utmip)
  @utmip = ::IPAddr.new(utmip).mask(24).to_s
  self
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



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/gabba/gabba.rb', line 263

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,
    :utmr => @utmr,
    :utmip => @utmip
  }
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")



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

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.



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

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,
    :utmr => @utmr,
    :utmip => @utmip
  }

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

  options
end

#random_id ⇒ Object 



363
364
365
 
# File 'lib/gabba/gabba.rb', line 363

def random_id
  rand 8999999999 + 1000000000
end

#referer(utmr) ⇒ Object

Public: provide the utmr attribute, allowing for referral tracking

Called before page_view etc

Examples:

g = Gabba::Gabba.new("UT-1234", "mydomain.com")
g.referer(request.env['HTTP_REFERER'])
g.page_view("something", "track/me")



316
317
318
319
 
# File 'lib/gabba/gabba.rb', line 316

def referer(utmr)
  @utmr = utmr
  self
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 50 for this custom variable (limit is 5 normally, but is 50 for GA Premium) 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



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

def set_custom_var(index, name, value, scope)
  raise "Index must be between 1 and 50" unless (1..50).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')



223
224
225
226
 
# File 'lib/gabba/gabba.rb', line 223

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



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/gabba/gabba.rb', line 230

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,
    :utmr => @utmr,
    :utmip => @utmip
  }
end