Google Analytics Reporting API Client for Ruby
Feel free to open an issue if you have a question that is not answered in the Wiki
We're trying out chat using Gitter Chat. I'll try to be in there whenever I'm at my computer.
If you've come here from Garb, welcome! There are a few changes from Garb, so you'll want to check out:
If you're not able to upgrade quite yet, Garb has been maintained https://github.com/Sija/garb
Get an OAuth2 Access Token from Google, Read about OAuth2
access_token = OAuth2 Access Token # from Google
Create a New User with the Access Token
user = Legato::User.new(access_token)
List the Accounts and Profiles of the first Account
user.accounts user.accounts.first.profiles
List all the Profiles the User has Access to
user.profiles
Get a Profile
profile = user.profiles.first
The Profile Carries the User
profile.user == user #=> true
The profile can also lookup its "parent" Web Property
profile.web_property
class Exit extend Legato::Modelmetrics :exits, :pageviews dimensions :page_path, :operating_system, :browser end
profile.exit #=> returns a Legato::Query profile.exit.each {} #=> any enumerable kicks off the request to GA
http://code.google.com/apis/analytics/docs/gdata/dimsmets/dimsmets.html
metrics :exits, :pageviews dimensions :page_path, :operating_system, :browser
Create named filters to wrap query filters.
Here's what google has to say: http://code.google.com/apis/analytics/docs/gdata/v3/reference.html#filters
Inside of any
Legato::Modelclass, the method
filteris available (like
metricsand
dimensions).
Return entries with exits counts greater than or equal to 2000
filter(:high_exits) {gte(:exits, 2000)}or ...
filter :high_exits, &lambda {gte(:exits, 2000)}
Return entries with pageview metric less than or equal to 200
filter(:low_pageviews) {lte(:pageviews, 200)}
Filters with dimensions
filter(:for_browser) {|browser| matches(:browser, browser)}
Filters with OR
filter(:browsers) {|*browsers| browsers.map {|browser| matches(:browser, browser)}}
Pass the profile as the first or last parameter into any filter.
Exit.for_browser("Safari", profile)
Chain two filters.
Exit.high_exits.low_pageviews(profile)
Profile gets a method for each class extended by Legato::Model
Exit.results(profile) == profile.exit
We can chain off of that method, too.
profile.exit.high_exits.low_pageviews.by_pageviews
Chaining order doesn't matter. Profile can be given to any filter.
Exit.high_exits(profile).low_pageviews == Exit.low_pageviews(profile).high_exits
Be sure to pass the appropriate number of arguments matching the lambda for your filter.
For a filter defined like this:
filter(:browsers) {|*browsers| browsers.map {|browser| matches(:browser, browser)}}
We can use it like this, passing any number of arguments:
Exit.browsers("Firefox", "Safari", profile)
Google Analytics supports a significant number of filtering options.
Here is what we can do currently: (the operator is a method available in filters for the appropriate metric or dimension)
Operators on metrics (method => GA equivalent):
eql => '==', not_eql => '!=', gt => '>', gte => '>=', lt => ' '<='
Operators on dimensions:
matches => '==', does_not_match => '!=', contains => '=~', does_not_contain => '!~', substring => '[email protected]', not_substring => '[email protected]'
Your query can have a session-level segment, which works with filter expressions. It works like an advanced segment, except you don't have to create it beforehand, you can just specify it at query time.
Some of the numbers you'll get will be different from using a filter, since the subset of visits matched happens before dimensions and metrics are calculated (hover on the
segmentparameter to see).
Some metrics and dimensions are not allowed for segments, see the API documentation for more details.
Note: Legato does not support Users vs Sessions, yet. The default will be sessions (the equivalent of the earlier, now removed, dynamic segments).
Return entries with exits counts greater than or equal to 2000
segment :high_exits do gte(:exits, 2000) end
Return entries with pageview metric less than or equal to 200
segment :low_pageviews do lte(:pageviews, 200) end
You can chain them
Exit.high_exits.low_pageviews(profile)
and call them directly on the profile
profile.exit.high_exits.low_pageviews
Legato::Management::Account.all(user) Legato::Management::WebProperty.all(user) Legato::Management::Profile.all(user) Legato::Management::Goal.all(user)
https://developers.google.com/analytics/devguides/reporting/realtime/v3/ https://developers.google.com/analytics/devguides/reporting/realtime/dimsmets/
GA provides an endpoint to do basic reporting in near-realtime. Please read the above documentation to know which features (and dimentsion/metrics) are or are not available. It is also only available in beta so you must already have access.
Inside of Legato, you can simply add
realtimeto your query (
#resultsreturns a
Queryinstance), like this:
Exit.results(profile).realtime
The results you iterate over (with
.each, etc) will be from the realtime reporting API.
You can also call
realtimeon your model to get a new
Queryinstance with realtime API set.
query = Exit.realtime query.realtime? #=> true query.tracking_scope #=> 'rt'
Assigning a
quota_useror
user_ipon a user instance will be used by management and query requests.
user = Legato::User.new(access_token) user.quota_user = 'some_unique_user_identifier' # OR user.user_ip = ip_address_from_a_web_user_or_something