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
 
# File 'lib/gattica/engine.rb', line 19

def initialize(options={})
  @options = Settings::DEFAULT_OPTIONS.merge(options)
  handle_init_options(@options)
  create_http_connection('www.google.com')
  check_init_auth_requirements()
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

#user_accounts ⇒ Object

Returns the value of attribute user_accounts.



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

def user_accounts
  @user_accounts
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.



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/gattica/engine.rb', line 44

def accounts
  if @user_accounts.nil?
    create_http_connection('www.googleapis.com')

    # get profiles
    response = do_http_get("/analytics/v2.4/management/accounts/~all/webproperties/~all/profiles?max-results=10000")
    xml = Hpricot(response)
    @user_accounts = xml.search(:entry).collect { |profile_xml| 
      Account.new(profile_xml) 
    }

    # Fill in the goals
    response = do_http_get("/analytics/v2.4/management/accounts/~all/webproperties/~all/profiles/~all/goals?max-results=10000")
    xml = Hpricot(response)
    @user_accounts.each do |ua|
      xml.search(:entry).each { |e| ua.set_goals(e) }
    end

    # Fill in the account name
    response = do_http_get("/analytics/v2.4/management/accounts?max-results=10000")
    xml = Hpricot(response)
    @user_accounts.each do |ua|
      xml.search(:entry).each { |e| ua.(e) }
    end

  end
  @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.



133
134
135
136
137
138
139
140
 
# File 'lib/gattica/engine.rb', line 133

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
  create_http_connection('www.googleapis.com')
  data = do_http_get("/analytics/v2.4/data?#{query_string}")
  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 })



87
88
89
90
91
92
93
94
95
96
 
# File 'lib/gattica/engine.rb', line 87

def segments
  if @user_segments.nil?
    response = do_http_get("/analytics/v2.4/management/segments?max-results=10000")
    xml = Hpricot(response)
    @user_segments = xml.search("dxp:segment").collect { |s| 
      Segment.new(s) 
    }
  end
  return @user_segments
end