Google Analytics API with Ruby and Garb: Making it Even Easier
Garb is now at 0.7.0! We’ve added many new features to make accessing Google Analytics even easier. Recently added features include: OAuth support, multiple user sessions, reporting extensions on profiles, and a library of basic classes to get new users running quickly (only three lines of code!). I’d like to cover some of the features that are now available as part of Garb, and how to make use of them.
Reporting Interface on Profile
The ideal way to define reports with Garb is by creating a new class, and extending it with the Garb::Resource module. With this class one could simply call
results and pass in a profile, and some options. This is all well and good, but when we’re always passing profile around, it seems like we should be able to work off of a profile itself.
In the latest Garb we can do the following given a profile and a class called Pageviews:
profile = Garb::Profile.first('UA-XXXXXX-XX')
class Pageviews extend Garb::Resource metrics :pageviews end
Now get those pageviews!
Simple! Any class defined which is extended with Garb::Resource immediately becomes available as a method on profile. We can even pass the same options to these methods, as we would to
profile.pageviews(:start_date => (Date.today-1), :end_date => Date.today, :limit => 20)
Thanks to John Nunemaker for the inspiration on this one.
Basic Report Library
In addition to making reports easily accessible on a profile, I’ve added a small collection of very basic reports to get new users going very quickly. If you simply
require 'garb/reports' you’ll have access to reports for bounces, exits, pageviews, unique_pageviews, and visits. I imagine I’ll continue to add to this library of reports as time goes on.
Now, the absolute simplest way to get going with Garb is three lines of code (aside from requiring garb and garb/reports):
Garb::Session.login('username', 'password') profile = Profile.first('UA-XXXXXX-XX') profile.visits
I hope this will make getting simple, commonly used metrics from Google Analytics even easier.
Again, thanks to John for suggesting I add this.
OAuth Token Support
OAuth provides one of the best methods for authentication of user accounts. It never requires that a user give us their username and password. But, it does give us information we can store to authenticate services without requiring the user re-authenticate frequently.
I have lamented not including OAuth support in Garb for a very long time. But, the truth was that I had no use for it myself. Thankfully, with the help of Nick Plante I was able to add the proper hooks to make use of an OAuth token. The OAuth dance must be implemented by your application (as Garb has no knowledge of the framework you may or may not be using). However, this is very simple, given the Ruby OAuth gem.
Once a token is acquired, you may provide it to Garb like so:
Garb::Session.access_token = OAuth::AccessToken.new(consumer, USER_TOKEN, USER_SECRET)
A more complete example is available in the wiki on OAuth Sessions.
Many thanks to Nick for providing the impetus, and code improvements.
The only other major feature missing from Garb’s authentication was the ability to have multiple sessions established. This feature would be critical if your application had users logging into their own analytics accounts (now using OAuth!). Previously, there was only one global session. Now, you can create a session instance, and pass it
Profile.first or to
Profile.all and that session will be used. Here’s an example:
session1 = Garb::Session.new session1.login('user1', 'password') profile1 = Garb::Profile.first('1234567', session1) session2 = Garb::Session.new session2.access_token = access_token profile2 = Garb::Profile.all(session2).first
It’s important to note that the global session and an instance of session share exactly the same method API. Furthermore, the global session method still works exactly as before.
Again, Many thanks to Nick Plante for pushing me to finish this, and for even more code contributions.
My hope is that these new features will make Garb an easier-to-use and more complete library for accessing Google Analytics with Ruby. Overall, I’m pretty satisfied with the way that Garb is progressing. If nothing major is wrong in this particular version, I’ll do some refactoring and call the next version 1.0. Leave comments if there are any features you’d like to see added before 1.0 and I’ll see if I can build them.