Class: Gattica::Engine

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Engine

Initialize Gattica using username/password or token.

Options:

To change the defaults see settings.rb

:debug

Send debug info to the logger (default is false)

:email

Your email/login for Google Analytics

:headers

Add additional HTTP headers (default is {} )

:logger

Logger to use (default is STDOUT)

:password

Your password for Google Analytics

:profile_id

Use this Google Analytics profile_id (default is nil)

:timeout

Set Net:HTTP timeout in seconds (default is 300)

:token

Use an authentication token you received before



19
20
21
22
23
24
25
 
# File 'lib/gattica/engine.rb', line 19

def initialize(options={})
  @options = Settings::DEFAULT_OPTIONS.merge(options)
  handle_init_options(@options)
  create_http_connection()
  check_init_auth_requirements()
  # TODO: check that the user has access to the specified profile and show an error here rather than wait for Google to respond with a message
end

Instance Attribute Details

#profile_id ⇒ Object

Returns the value of attribute profile_id.



5
6
7
 
# File 'lib/gattica/engine.rb', line 5

def profile_id
  @profile_id
end

#token ⇒ Object

Returns the value of attribute token.



5
6
7
 
# File 'lib/gattica/engine.rb', line 5

def token
  @token
end

#user ⇒ Object (readonly)

Returns the value of attribute user.



4
5
6
 
# File 'lib/gattica/engine.rb', line 4

def user
  @user
end

Instance Method Details

#accounts ⇒ Object

Returns the list of accounts the user has access to. A user may have multiple accounts on Google Analytics and each account may have multiple profiles. You need the profile_id in order to get info from GA. If you don’t know the profile_id then use this method to get a list of all them. Then set the profile_id of your instance and you can make regular calls from then on.

ga = Gattica.new({:email => '[email protected]', :password => 'password'})
ga.accounts
# you parse through the accounts to find the profile_id you need
ga.profile_id = 12345678
# now you can perform a regular search, see Gattica::Engine#get

If you pass in a profile id when you instantiate Gattica::Search then you won’t need to get the accounts and find a profile_id - you apparently already know it!

See Gattica::Engine#get to see how to get some data.



45
46
47
48
49
50
51
52
53
 
# File 'lib/gattica/engine.rb', line 45

def accounts
  # if we haven't retrieved the user's accounts yet, get them now and save them
  if @user_accounts.nil?
    data = 
    xml = Hpricot(data)
    @user_accounts = xml.search(:entry).collect { |entry| Account.new(entry) }
  end
  return @user_accounts
end

#get(args = {}) ⇒ Object

This is the method that performs the actual request to get data.

Usage

gs = Gattica.new({:email => '[email protected]', :password => 'password', :profile_id => 123456})
gs.get({ :start_date => '2008-01-01',
         :end_date => '2008-02-01',
         :dimensions => 'browser',
         :metrics => 'pageviews',
         :sort => 'pageviews',
         :filters => ['browser == Firefox']})

Input

When calling get you’ll pass in a hash of options. For a description of what these mean to Google Analytics, see code.google.com/apis/analytics/docs

Required values are:

  • start_date => Beginning of the date range to search within

  • end_date => End of the date range to search within

Optional values are:

  • dimensions => an array of GA dimensions (without the ga: prefix)

  • metrics => an array of GA metrics (without the ga: prefix)

  • filter => an array of GA dimensions/metrics you want to filter by (without the ga: prefix)

  • sort => an array of GA dimensions/metrics you want to sort by (without the ga: prefix)

Exceptions

If a user doesn’t have access to the profile_id you specified, you’ll receive an error. Likewise, if you attempt to access a dimension or metric that doesn’t exist, you’ll get an error back from Google Analytics telling you so.



113
114
115
116
117
118
119
120
 
# File 'lib/gattica/engine.rb', line 113

def get(args={})
  args = validate_and_clean(Settings::DEFAULT_ARGS.merge(args))
  query_string = build_query_string(args,@profile_id)
  @logger.debug(query_string) if @debug
  data = do_http_get("/analytics/feeds/data?#{query_string}")
  #data = do_http_get("/analytics/feeds/data?ids=ga%3A915568&metrics=ga%3Avisits&segment=gaid%3A%3A-7&start-date=2010-03-29&end-date=2010-03-29&max-results=50")
  return DataSet.new(Hpricot.XML(data))
end

#segments ⇒ Object

Returns the list of segments available to the authenticated user.

Usage

ga = Gattica.new({:email => '[email protected]', :password => 'password'})
ga.segments                       # Look up segment id
my_gaid = 'gaid::-5'              # Non-paid Search Traffic
ga.profile_id = 12345678          # Set our profile ID

gs.get({ :start_date => '2008-01-01',
         :end_date => '2008-02-01',
         :dimensions => 'month',
         :metrics => 'views',
         :segment => my_gaid })



69
70
71
72
73
74
75
76
 
# File 'lib/gattica/engine.rb', line 69

def segments
  if @user_segments.nil?
    data = 
    xml = Hpricot(data)
    @user_segments = xml.search("dxp:segment").collect { |s| Segment.new(s) }
  end
  return @user_segments
end