readmedia-garb 0.9.1.1

data/README.md

@@ -0,0 +1,198 @@
+Garb
+====
+
+  Originally forked from: http://github.com/vigetlabs/garb
+
+Important Changes
+=================
+
+  Philip Brocoum (readMedia): Google deprecated their API version 2.3 on
+  Thursday, August 23, 2012. Version 2.4 of the API is mostly
+  backward-compatible except there are new URL endpoints, which have been
+  updated in this release of 0.9.1.1.
+
+  With The release of version 0.9.0 I have officially deprecated Garb::Report, Garb::Resource,
+  Garb::Profile, and Garb::Account. Garb::Report and Garb::Resource should be replaced by Garb::Model.
+  Garb::Profile and Garb::Account are supplanted by their Garb::Management::* counterparts.
+  
+  I'll be working hard to update the documentation over the next day or so to highlight all of the
+  old features in the new classes, as well as any new features brought by the new classes. If you
+  are looking for something in particular, please open an issue and I will try to prioritize these
+  requests.
+
+  Please read CHANGELOG
+
+Description
+-----------
+
+  Provides a Ruby API to the Google Analytics API.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
+
+Basic Usage
+===========
+
+Single User Login
+-----------------
+  
+    > Garb::Session.login(username, password)
+    
+OAuth Access Token
+------------------
+
+    > Garb::Session.access_token = access_token # assign from oauth gem
+
+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
+
+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.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html#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.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataReference.html#filtering
+
+  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 http://curl.haxx.se/ca/cacert.pem into your application somewhere.
+  Then, define a constant CA_CERT_FILE and point 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.
+
+TODOS
+-----
+
+  * rebuild AND/OR filtering in Garb::Model
+
+Requirements
+------------
+
+  * crack >= 0.1.6
+  * active_support >= 2.2.0
+
+Requirements for Testing
+------------------------
+
+  * shoulda
+  * jferris-mocha
+
+Install
+-------
+
+    gem install garb
+
+Contributors
+------------
+
+  Many Thanks, for all their help, goes to:
+
+  * Patrick Reagan
+  * Justin Marney
+  * Nick Plante
+
+License
+-------
+
+  (The MIT License)
+
+  Copyright (c) 2010 Viget Labs
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  'Software'), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'garb'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'readmedia-garb'
+  s.version           = Garb::Version.to_s
+  s.has_rdoc          = false
+  s.rubyforge_project = 'readmedia'
+  s.summary           = "Google Analytics API (v2.4) Ruby Wrapper"
+  s.authors           = ['Tony Pitale, Philip Brocoum (readMedia)']
+  s.email             = 'Developer@readMedia.com'
+  s.homepage          = 'http://github.com/readmedia/garb'
+  s.files             = %w(README.md Rakefile) + Dir.glob("lib/**/*")
+  s.test_files        = Dir.glob("test/**/*")
+
+  s.add_dependency("crack", [">= 0.1.6"])
+  s.add_dependency("activesupport", [">= 2.2.0"])
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end
+
+begin
+  require 'rcov/rcovtask'
+
+  desc "Generate RCov coverage report"
+  Rcov::RcovTask.new(:rcov) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts << "-x \"test/*,gems/*,/Library/Ruby/*,config/*\" -x lib/garb.rb -x lib/garb/version.rb --rails" 
+  end
+rescue LoadError
+  nil
+end
+
+task :default => 'test'
+
+# EOF

data/lib/garb/account.rb

@@ -0,0 +1,22 @@
+module Garb
+  class Account
+    attr_reader :id, :name, :profiles
+
+    def initialize(profiles)
+      @id = profiles.first.account_id    
+      @name = profiles.first.account_name
+      @profiles = profiles
+    end
+
+    def self.all(session = Session)
+      ActiveSupport::Deprecation.warn("The use of Garb::Account has been deprecated in favor of 'Garb::Management::Account'")
+      profiles = {}
+
+      Profile.all(session).each do |profile|
+        (profiles[profile.account_id] ||= []) << profile
+      end
+
+      profiles.map {|k,v| v}.map {|profiles| new(profiles)}
+    end
+  end
+end

data/lib/garb/account_feed_request.rb

@@ -0,0 +1,25 @@
+module Garb
+  class AccountFeedRequest
+    URL = "https://www.google.com/analytics/feeds/accounts/default"
+
+    def initialize(session = Session)
+      @request = DataRequest.new(session, URL)
+    end
+
+    def response
+      @response ||= @request.send_request
+    end
+
+    def parsed_response
+      @parsed_response ||= Crack::XML.parse(response.body)
+    end
+
+    def entries
+      parsed_response ? Array(parsed_response['feed']['entry']).flatten.compact : []
+    end
+
+    def segments
+      parsed_response ? Array(parsed_response['feed']['dxp:segment']).flatten.compact : []
+    end
+  end
+end

data/lib/garb/authentication_request.rb

@@ -0,0 +1,53 @@
+module Garb
+  class AuthenticationRequest
+    class AuthError < StandardError;end
+
+    URL = 'https://www.google.com/accounts/ClientLogin'
+
+    def initialize(email, password, opts={})
+      @email = email
+      @password = password
+      @account_type = opts.fetch(:account_type, 'HOSTED_OR_GOOGLE')
+    end
+
+    def parameters
+      {
+        'Email'       => @email,
+        'Passwd'      => @password,
+        'accountType' => @account_type,
+        'service'     => 'analytics',
+        'source'      => 'vigetLabs-garb-001'
+      }
+    end
+    
+    def uri
+      URI.parse(URL)
+    end
+
+    def send_request(ssl_mode)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = ssl_mode
+
+      if ssl_mode == OpenSSL::SSL::VERIFY_PEER
+        http.ca_file = CA_CERT_FILE
+      end
+
+      http.request(build_request) do |response|
+        raise AuthError unless response.is_a?(Net::HTTPOK)
+      end
+    end
+
+    def build_request
+      post = Net::HTTP::Post.new(uri.path)
+      post.set_form_data(parameters)
+      post
+    end
+    
+    def auth_token(opts={})
+      ssl_mode = opts[:secure] ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      send_request(ssl_mode).body.match(/^Auth=(.*)$/)[1]
+    end
+
+  end
+end

data/lib/garb/data_request.rb

@@ -0,0 +1,42 @@
+module Garb
+  class DataRequest
+    class ClientError < StandardError; end
+
+    def initialize(session, base_url, parameters={})
+      @session = session
+      @base_url = base_url
+      @parameters = parameters
+    end
+
+    def query_string
+      parameter_list = @parameters.map {|k,v| "#{k}=#{v}" }
+      parameter_list.empty? ? '' : "?#{parameter_list.join('&')}"
+    end
+
+    def uri
+      URI.parse(@base_url)
+    end
+
+    def send_request
+      response = if @session.single_user?
+        single_user_request
+      elsif @session.oauth_user?
+        oauth_user_request
+      end
+
+      raise ClientError, response.body.inspect unless response.kind_of?(Net::HTTPSuccess)
+      response
+    end
+
+    def single_user_request
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      http.get("#{uri.path}#{query_string}", {'Authorization' => "GoogleLogin auth=#{@session.auth_token}", 'GData-Version' => '2'})
+    end
+
+    def oauth_user_request
+      @session.access_token.get("#{uri}#{query_string}", {'GData-Version' => '2'})
+    end
+  end
+end

data/lib/garb/destination.rb

@@ -0,0 +1,18 @@
+module Garb
+  class Destination
+    attr_reader :match_type, :expression, :steps, :case_sensitive
+
+    alias :case_sensitive? :case_sensitive
+
+    def initialize(attributes)
+      return unless attributes.is_a?(Hash)
+
+      @match_type = attributes['matchType']
+      @expression = attributes['expression']
+      @case_sensitive = (attributes['caseSensitive'] == 'true')
+
+      step_attributes = attributes[Garb.to_ga('step')]
+      @steps = Array(step_attributes.is_a?(Hash) ? [step_attributes] : step_attributes).map {|s| Step.new(s)}
+    end
+  end
+end

data/lib/garb/filter_parameters.rb

@@ -0,0 +1,42 @@
+module Garb
+  class FilterParameters
+    def self.define_operators(*methods)
+      methods.each do |method|
+        class_eval <<-CODE
+          def #{method}(field, value)
+            @filter_hash.merge!({SymbolOperator.new(field, :#{method}) => value})
+          end
+        CODE
+      end
+    end
+
+    define_operators :eql, :not_eql, :gt, :gte, :lt, :lte, :matches,
+      :does_not_match, :contains, :does_not_contain, :substring, :not_substring
+
+    attr_accessor :parameters
+
+    def initialize
+      self.parameters = []
+    end
+
+    def filters(&block)
+      @filter_hash = {}
+
+      instance_eval &block
+
+      self.parameters << @filter_hash
+    end
+
+    def to_params
+      value = self.parameters.map do |param|
+        param.map do |k,v|
+          next unless k.is_a?(SymbolOperator)
+          escaped_v = v.to_s.gsub(/([,;\\])/) {|c| '\\'+c}
+          "#{URI.encode(k.to_google_analytics, /[=<>]/)}#{CGI::escape(escaped_v)}"
+        end.join('%3B') # Hash AND (no duplicate keys), escape char for ';' fixes oauth
+      end.join(',') # Array OR
+
+      value.empty? ? {} : {'filters' => value}
+    end
+  end
+end

data/lib/garb/goal.rb

@@ -0,0 +1,20 @@
+module Garb
+  class Goal
+    attr_reader :name, :number, :value, :destination
+
+    def initialize(attributes={})
+      return unless attributes.is_a?(Hash)
+
+      @name = attributes['name']
+      @number = attributes['number'].to_i
+      @value = attributes['value'].to_f
+      @active = (attributes['active'] == 'true')
+
+      @destination = Destination.new(attributes[Garb.to_ga('destination')])
+    end
+
+    def active?
+      @active
+    end
+  end
+end

data/lib/garb/management/account.rb

@@ -0,0 +1,39 @@
+module Garb
+  module Management
+    class Account
+      attr_accessor :session, :path
+      attr_accessor :id, :title, :name
+
+      def self.all(session = Session)
+        feed = Feed.new(session, '/accounts')
+        feed.entries.map {|entry| new_from_entry(entry, session)}
+      end
+
+      def self.new_from_entry(entry, session)
+        account = new
+        account.session = session
+        account.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
+        account.title = entry['title'].gsub('Google Analytics Account ', '') # can we get this in properties=?
+        account.properties = Garb.parse_properties(entry)
+        account
+      end
+
+      def properties=(properties)
+        self.id = properties["account_id"]
+        self.name = properties["account_name"]
+      end
+
+      def web_properties
+        @web_properties ||= WebProperty.for_account(self)
+      end
+
+      def profiles
+        @profiles ||= Profile.for_account(self)
+      end
+
+      def goals
+        @goals ||= Goal.for_account(self)
+      end
+    end
+  end
+end

data/lib/garb/management/feed.rb

@@ -0,0 +1,26 @@
+module Garb
+  module Management
+    class Feed
+      BASE_URL = "https://www.google.com/analytics/feeds/datasources/ga"
+
+      attr_reader :request
+
+      def initialize(session, path)
+        @request = DataRequest.new(session, BASE_URL+path)
+      end
+
+      def parsed_response
+        @parsed_response ||= Crack::XML.parse(response.body)
+      end
+
+      def entries
+        # possible to have nil entries, yuck
+        parsed_response ? [parsed_response['feed']['entry']].flatten.compact : []
+      end
+
+      def response
+        @response ||= request.send_request
+      end
+    end
+  end
+end

data/lib/garb/management/goal.rb

@@ -0,0 +1,44 @@
+module Garb
+  module Management
+    class Goal
+
+      attr_accessor :session, :path
+      attr_accessor :name, :number, :value, :destination, :active
+
+      alias :active? :active
+
+      def self.all(session = Session, path = '/accounts/~all/webproperties/~all/profiles/~all/goals')
+        feed = Feed.new(session, path)
+        feed.entries.map {|entry| new_from_entry(entry, session)}
+      end
+
+      def self.for_account(account)
+        all(account.session, account.path + '/webproperties/~all/profiles/~all/goals')
+      end
+
+      def self.for_web_property(web_property)
+        all(web_property.session, web_property.path + '/profiles/~all/goals')
+      end
+
+      def self.for_profile(profile)
+        all(profile.session, profile.path + '/goals')
+      end
+
+      def self.new_from_entry(entry, session)
+        goal = new
+        goal.session = session
+        goal.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
+        goal.properties = entry[Garb.to_ga('goal')]
+        goal
+      end
+
+      def properties=(properties)
+        self.name = properties["name"]
+        self.number = properties["number"].to_i
+        self.value = properties["value"].to_f
+        self.active = (properties["active"] == "true")
+        self.destination = Destination.new(properties[Garb.to_ga('destination')])
+      end
+    end
+  end
+end

data/lib/garb/management/profile.rb

@@ -0,0 +1,44 @@
+module Garb
+  module Management
+    class Profile
+
+      include ProfileReports
+
+      attr_accessor :session, :path
+      attr_accessor :id, :table_id, :title, :account_id, :web_property_id
+
+      def self.all(session = Session, path = '/accounts/~all/webproperties/~all/profiles')
+        feed = Feed.new(session, path)
+        feed.entries.map {|entry| new_from_entry(entry, session)}
+      end
+
+      def self.for_account(account)
+        all(account.session, account.path+'/webproperties/~all/profiles')
+      end
+
+      def self.for_web_property(web_property)
+        all(web_property.session, web_property.path+'/profiles')
+      end
+
+      def self.new_from_entry(entry, session)
+        profile = new
+        profile.session = session
+        profile.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
+        profile.properties = Garb.parse_properties(entry)
+        profile
+      end
+
+      def properties=(properties)
+        self.id = properties['profile_id']
+        self.table_id = properties['dxp:table_id']
+        self.title = properties['profile_name']
+        self.account_id = properties['account_id']
+        self.web_property_id = properties['web_property_id']
+      end
+
+      def goals
+        Goal.for_profile(self)
+      end
+    end
+  end
+end

data/lib/garb/management/segment.rb

@@ -0,0 +1,27 @@
+module Garb
+  module Management
+    class Segment
+      attr_accessor :session, :path
+      attr_accessor :id, :name, :definition
+
+      def self.all(session = Session)
+        feed = Feed.new(session, '/segments')
+        feed.entries.map {|entry| new_from_entry(entry, session)}
+      end
+
+      def self.new_from_entry(entry, session)
+        segment = new
+        segment.session = session
+        segment.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
+        segment.properties = entry['dxp:segment']
+        segment
+      end
+
+      def properties=(properties)
+        self.id = properties['id']
+        self.name = properties['name']
+        self.definition = properties['dxp:definition']
+      end
+    end
+  end
+end