Skip to content

Latest commit

 

History

History
222 lines (155 loc) · 5.26 KB

README.md

File metadata and controls

222 lines (155 loc) · 5.26 KB
Raw

Garb Gem Version CI License

https://github.com/Sija/garb

Google Shutting Down Deprecated Auth on April 20th, 2015

On April 20th, Google will be shutting down ClientLogin, AuthSub, and OAuth 1.0. https://groups.google.com/forum/#!topic/google-analytics-api-notify/g8wbdUqEDd0

Legato

There's rewritten and (moar) actively maintained version of the library in the form of Legato. You might want to check it out as it's mostly compatible with Garb.

Important Changes

This fork contains heavily modified version of vigetlab's Garb library. It works only with version 3 of Google API.

Please read CHANGELOG.

Description

Provides a Ruby API to the Google Analytics API.

https://developers.google.com/analytics/devguides/reporting/core/v3/coreDevguide

Basic Usage

Single User Login

Garb::Session.api_key = api_key # required for 2-step authentication
Garb::Session.login(username, password)

OAuth Access Token

Garb::Session.access_token = access_token # an instance of OAuth2::Client

Accounts, WebProperties, Profiles, and Goals

Garb::Management::Account.all
Garb::Management::WebProperty.all
Garb::Management::Profile.all
Garb::Management::Goal.all

Profiles for a UA- Number (a WebProperty)

profile = Garb::Management::Profile.all.detect { |p| p.web_property_id == 'UA-XXXXXXX-X' }

Define a Report Class

class Exits
  extend Garb::Model

  metrics :exits, :pageviews
  dimensions :page_path
end

Get the Results

Exits.results(profile, filters: { :page_path.eql => '/' })

OR shorthand

profile.exits(filters: { :page_path.eql => '/' })

Be forewarned, these numbers are for the last 30 days and may be slightly different from the numbers displayed in Google Analytics' dashboard for 1 month.

Other Parameters

  • start_date: The date of the period you would like this report to start
  • end_date: The date to end, inclusive
  • limit: The maximum number of results to be returned
  • offset: The starting index
  • all: Return all results if true (which might result in several requests to GAPI)
  • sampling_level: Specify precision vs speed strategy (default, faster, greater_precision)

Metrics & Dimensions

Metrics and Dimensions are very complex because of the ways in which they can and cannot be combined.

I suggest reading the google documentation to familiarize yourself with this.

https://developers.google.com/analytics/devguides/reporting/core/dimsmets#q=bouncerate

When you've returned, you can pass the appropriate combinations to Garb, as symbols.

Filtering

Google Analytics supports a significant number of filtering options.

https://developers.google.com/analytics/devguides/reporting/core/v3/reference#filters

Here is what we can do currently: (the operator is a method on a symbol for the appropriate metric or dimension)

Operators on metrics:

:eql      => '==',
:not_eql  => '!=',
:gt       => '>',
:gte      => '>=',
:lt       => '<',
:lte      => '<='

Operators on dimensions:

:matches          => '==',
:does_not_match   => '!=',
:contains         => '=~',
:does_not_contain => '!~',
:substring        => '=@',
:not_substring    => '!@'

Given the previous Exits example report in shorthand, we can add an option for filter:

profile.exits(filters: { :page_path.eql => '/extend/effectively-using-git-with-subversion/' })

SSL

Version 0.2.3 includes support for real ssl encryption for SINGLE USER authentication. First do:

Garb::Session.login(username, password, secure: true)

Next, be sure to download https://curl.haxx.se/ca/cacert.pem into your application somewhere. Then, point Garb.ca_cert_file property to that file.

For whatever reason, simply creating a new certificate store and setting the defaults would not validate the google ssl certificate as authentic.

OPEN / READ TIMEOUT

The open and read timeout values used with the network client (Net::HTTP) are configurable. Both values default to 60 seconds.

Garb.open_timeout = 3
Garb.read_timeout = 3

TODOS

  • rebuild AND/OR filtering in Garb::Model

Requirements

  • active_support >= 2.2
  • multi_json >= 1.3

Requirements for Testing

  • shoulda
  • mocha
  • bourne

Install

Add this line to your application’s Gemfile:

gem 'garb'

Then run:

bundle install

Contributors

Many Thanks, for all their help, goes to:

  • Patrick Reagan
  • Justin Marney
  • Nick Plante
  • James Cook
  • Chris Gunther
  • Sijawusz Pur Rahnama