google_analytics_feeds 0.1.1 → 0.1.2

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - rbx-18mode
+  - rbx-19mode
+  - 1.8.7
+  - ree
+  - ruby-head
+notifications:
+  recipients:
+    - roland.swingler@gmail.com

data/.yardopts

@@ -0,0 +1 @@
+--api public

data/Gemfile

@@ -8,7 +8,7 @@ gem "addressable"
 # Include everything needed to run rake, tests, features, etc.
 group :development do
   gem "rspec", "~> 2"
-  gem "rdoc", "~> 3.12"
+  gem "yard"
   gem "jeweler", "~> 1.8"
-  gem "rcov", ">= 0"
+  gem "rcov", ">= 0", :platforms => :mri_18
 end

data/README.rdoc

@@ -1,8 +1,18 @@
 = Google Analytics Feeds
 
-Allows access to google analytics feeds from ruby.
+{<img src="https://secure.travis-ci.org/knaveofdiamonds/google_analytics_feeds.png" />}[http://travis-ci.org/knaveofdiamonds/google_analytics_feeds]
 
-Does not support any of the OAuth-related authentication methods.
+Allows access to Google Analytics feeds from Ruby.
+
+Does not support any of the OAuth-related authentication methods, only
+session login.
+
+It tries to be really simple, returning rows as Hashes rather than
+specific objects, and provides flexibility as to how you want to make
+HTTP calls via Faraday.
+
+Tested on 1.9, 1.8 & Rubinus; depends on Ox, which has C dependencies
+so not tested on JRuby.
 
 == Installation
 
@@ -26,7 +36,7 @@ Does not support any of the OAuth-related authentication methods.
     session.login("username", "password")
 
     # Fetch a report. Rows are handled with a 
-    # GoogleAnalyticsFeed::RowHandler - this may just be an anonymous
+    # GoogleAnalyticsFeeds::RowHandler - this may just be an anonymous
     # block as demonstrated here.
     session.fetch_report(report) do
       def row(r)
@@ -34,10 +44,24 @@ Does not support any of the OAuth-related authentication methods.
       end
     end
 
+    # Or you can pass a RowHandler class
+    class StdoutRowHandler < GoogleAnalyticsFeeds::RowHandler
+      def row(r)
+        puts r.inspect
+      end
+    end
+
+    # Either takes the class
+    session.fetch_report(report, StdoutRowHandler)
+
+    # Or an instance (if you needed to pass things to the constructor)
+    session.fetch_report(report, StdoutRowHandler.new)
+
+For detailed documentation on how to use the Google Analytics Data Feeds, see Google's documentation: https://developers.google.com/analytics/devguides/reporting/core/v2/gdataReferenceDataFeed
+
 == TODO
 
-* Tests, documentation
-* Filters
+* More tests, documentation.
 * Access to the management data feed.
 * Auto-follow of paginated result sets.
 

data/Rakefile

@@ -36,14 +36,7 @@ RSpec::Core::RakeTask.new(:rcov) do |spec|
   spec.rcov = true
 end
 
-task :default => :spec
-
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+require 'yard'
+YARD::Rake::YardocTask.new
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "google_analytics_feeds #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+task :default => :spec

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/google_analytics_feeds.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{google_analytics_feeds}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Roland Swingler}]
-  s.date = %q{2012-08-31}
+  s.date = %q{2012-10-16}
   s.description = %q{Fairly low-level client library to access Google Analytics Feeds}
   s.email = %q{roland.swingler@gmail.com}
   s.extra_rdoc_files = [
@@ -19,6 +19,8 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
     ".rspec",
+    ".travis.yml",
+    ".yardopts",
     "Gemfile",
     "LICENSE.txt",
     "README.rdoc",
@@ -26,9 +28,9 @@ Gem::Specification.new do |s|
     "VERSION",
     "google_analytics_feeds.gemspec",
     "lib/google_analytics_feeds.rb",
-    "lib/sample.rb",
     "spec/google_analytics_feeds_spec.rb",
     "spec/request_spec.rb",
+    "spec/session_spec.rb",
     "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/knaveofdiamonds/google_analytics_feeds}
@@ -45,7 +47,7 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<faraday>, [">= 0"])
       s.add_runtime_dependency(%q<addressable>, [">= 0"])
       s.add_development_dependency(%q<rspec>, ["~> 2"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.8"])
       s.add_development_dependency(%q<rcov>, [">= 0"])
     else
@@ -53,7 +55,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<faraday>, [">= 0"])
       s.add_dependency(%q<addressable>, [">= 0"])
       s.add_dependency(%q<rspec>, ["~> 2"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<yard>, [">= 0"])
       s.add_dependency(%q<jeweler>, ["~> 1.8"])
       s.add_dependency(%q<rcov>, [">= 0"])
     end
@@ -62,7 +64,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<faraday>, [">= 0"])
     s.add_dependency(%q<addressable>, [">= 0"])
     s.add_dependency(%q<rspec>, ["~> 2"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<yard>, [">= 0"])
     s.add_dependency(%q<jeweler>, ["~> 1.8"])
     s.add_dependency(%q<rcov>, [">= 0"])
   end

data/lib/google_analytics_feeds.rb

@@ -3,17 +3,35 @@ require 'addressable/uri'
 require 'stringio'
 require 'faraday'
 
+# @api public
 module GoogleAnalyticsFeeds
+  # Raised if login fails.
+  #
+  # @api public
   class AuthenticationError < StandardError ; end
+  
+  # Raised if there is an HTTP-level problem retrieving reports.
+  #
+  # @api public
   class HttpError < StandardError ; end
 
+  # A Google Analytics session, used to retrieve reports.
+  # @api public
   class Session
+    # @api private
     CLIENT_LOGIN_URI = "https://www.google.com/accounts/ClientLogin"
 
+    # Creates a new session.
+    #
+    # Optionally pass a Faraday connection, otherwise uses the default
+    # Faraday connection.
     def initialize(connection=Faraday.default_connection)
       @connection = connection
     end
 
+    # Log in to Google Analytics with username and password
+    #
+    # This should be done before attempting to fetch any reports.
     def login(username, password)
       return @token if @token
       response = @connection.post(CLIENT_LOGIN_URI,
@@ -30,6 +48,10 @@ module GoogleAnalyticsFeeds
       end
     end
 
+    # Retrieve a report from Google Analytics.
+    #
+    # Rows are yielded to a RowHandler, provided either as a class,
+    # instance or a block.
     def fetch_report(report, handler=nil, &block)
       handler  = block if handler.nil?
       response = report.retrieve(@token, @connection)
@@ -46,17 +68,32 @@ module GoogleAnalyticsFeeds
   #
   # Extend this class and override the methods you care about to
   # handle data feed row data.
+  #
+  # @abstract
+  # @api public
   class RowHandler
+    # Called before any row is parsed.
+    #
+    # By default, does nothing.
     def start_rows
     end
 
+    # Called when each row is parsed.
+    #
+    # By default, does nothing.
+    #
+    # @param row Hash
     def row(row)
     end
 
+    # Called after all rows have been parsed.
+    #
+    # By default, does nothing.
     def end_rows
     end
   end
   
+  # @api private
   module Naming
     # Returns a ruby-friendly symbol from a google analytics name.
     #
@@ -81,6 +118,8 @@ module GoogleAnalyticsFeeds
 
   # Parses rows from the GA feed via SAX. Clients shouldn't have to
   # use this - use a RowHandler instead.
+  #
+  # @api private
   class RowParser < ::Ox::Sax
     include Naming
 
@@ -133,6 +172,9 @@ module GoogleAnalyticsFeeds
     end
   end
 
+  # Construct filters for a DataFeed.
+  # 
+  # @api private
   class FilterBuilder
     include Naming
 
@@ -194,6 +236,7 @@ module GoogleAnalyticsFeeds
     end
   end
 
+  # @api public
   class DataFeed
     include Naming
     
@@ -203,24 +246,44 @@ module GoogleAnalyticsFeeds
       @params = {}
     end
 
+    # Sets the profile id from which this report should be based.
+    #
+    # @return [GoogleAnalyticsFeeds::DataFeed] a cloned DataFeed.
     def profile(id)
       clone_and_set {|params|
         params['ids'] = symbol_to_name(id)
       }
     end
 
+    # Sets the metrics for a query.
+    #
+    # A query must have at least 1 metric for GA to consider it
+    # valid. GA also imposes a maximum (as of writing 10 metrics) per
+    # query.
+    #
+    # @param names [*Symbol] the ruby-style names of the dimensions.
+    # @return [GoogleAnalyticsFeeds::DataFeed] a cloned DataFeed.
     def metrics(*vals)
       clone_and_set {|params|
         params['metrics'] = vals.map {|v| symbol_to_name(v) }.join(',')
       }
     end
 
-    def dimensions(*vals)
+    # Sets the dimensions for a query.
+    #
+    # A query doesn't have to have any dimensions; Google Analytics
+    # limits you to 7 dimensions per-query at time of writing.
+    #
+    # @param names [*Symbol] the ruby-style names of the dimensions.
+    # @return [GoogleAnalyticsFeeds::DataFeed] a cloned DataFeed.
+    def dimensions(*names)
       clone_and_set {|params|
-        params['dimensions'] = vals.map {|v| symbol_to_name(v) }.join(',')
+        params['dimensions'] = names.map {|v| symbol_to_name(v) }.join(',')
       }
     end
 
+    # Sets the start and end date for retrieved results
+    # @return [GoogleAnalyticsFeeds::DataFeed] a cloned DataFeed.
     def dates(start_date, end_date)
       clone_and_set {|params|
         params['start-date'] = start_date.strftime("%Y-%m-%d")
@@ -228,25 +291,58 @@ module GoogleAnalyticsFeeds
       }
     end
 
+    # Sets the start index for retrieved results
+    # @return [GoogleAnalyticsFeeds::DataFeed]
     def start_index(i)
       clone_and_set {|params|
         params['start-index'] = i.to_s
       }
     end
 
+    # Sets the maximum number of results retrieved.
+    #
+    # Google Analytics has its own maximum as well.
+    # @return [GoogleAnalyticsFeeds::DataFeed]
     def max_results(i)
       clone_and_set {|params|
         params['max-results'] = i.to_s
       }
     end
 
+    # Filter the result set, based on the results of a block.
+    #
+    # All the block methods follow the form operator(name,
+    # value). Supported operators include: eql, not_eql, lt, lte, gt,
+    # gte, contains, not_contains, match and not_match - hopefully all
+    # self-explainatory.
+    #
+    # Example:
+    #
+    #    query.
+    #      filter {
+    #        eql(:dimension, "value")
+    #        gte(:metric, 3)
+    #      }
+    # 
+    # @return [GoogleAnalyticsFeeds::DataFeed]
     def filters(&block)
-      builder = 
       clone_and_set {|params|
         params['filters'] = FilterBuilder.new.build(&block)
       }
     end
 
+    # Use a dynamic advanced segment.
+    #
+    # Block methods follow the same style as for filters. Named
+    # advanced segments are not yet supported.
+    # 
+    # @return [GoogleAnalyticsFeeds::DataFeed]
+    def segment(&block)
+      clone_and_set {|params|
+        params['segment'] = "dynamic::" + FilterBuilder.new.build(&block)
+      }
+    end
+
     # Sorts the result set by a column.
     #
     # Direction can be :asc or :desc.
@@ -257,14 +353,16 @@ module GoogleAnalyticsFeeds
       }
     end
 
+    # Returns the URI string needed to retrieve this report.
     def uri
       uri = Addressable::URI.parse(BASE_URI)
       uri.query_values = @params
-      uri.to_s.gsub("%40", "~")
+      uri.to_s.gsub("%40", "@")
     end
 
     alias :to_s :uri
 
+    # @api private
     def retrieve(session_token, connection)
       connection.get(uri) do |request|
         request.headers['Authorization'] = 
@@ -272,6 +370,7 @@ module GoogleAnalyticsFeeds
       end
     end
 
+    # @api private
     def clone
       obj = super
       obj.instance_variable_set(:@params, @params.clone)
@@ -291,6 +390,7 @@ module GoogleAnalyticsFeeds
     end
   end
 
+  # @api private
   class DataFeedParser
     def initialize(handler)
       if handler.kind_of?(Proc)

data/spec/request_spec.rb

@@ -57,4 +57,16 @@ describe GoogleAnalyticsFeeds::DataFeed do
       "filters" => "ga:baz==4;ga:foo=@123"
     }
   end
+
+  it "can add a dynamic segment" do
+    feed = described_class.new.
+      segment {
+      eql :medium, "referral"
+    }
+
+    uri = Addressable::URI.parse(feed.uri)
+    uri.query_values.should == {
+      "segment" => "dynamic::ga:medium==referral"
+    }
+  end
 end

data/spec/session_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe GoogleAnalyticsFeeds::Session do
+  it "raises an AuthenticationError if login is not a success" do
+    connection = stub(:connection, :post => stub(:response, :success? => false))
+    expect {
+      described_class.new(connection).login('name', 'password')
+    }.to raise_error(GoogleAnalyticsFeeds::AuthenticationError)
+  end
+
+  it "sets and returns a token if login is a success" do
+    connection = stub(:connection, :post => stub(:response, :success? => true, :body => "Auth=MYTOKEN"))
+    described_class.new(connection).login('name', 'password').should == "MYTOKEN"
+  end
+
+  it "posts the username and email to Google Analytics" do
+    connection = mock(:connection)
+    connection.should_receive(:post).
+      with("https://www.google.com/accounts/ClientLogin",
+           'Email' => 'me@example.com',
+           'Passwd' => 'password',
+           'accountType' => 'HOSTED_OR_GOOGLE',
+           'service' => 'analytics',
+           'source' => 'ruby-google-analytics-feeds').
+      and_return(stub(:response, :success? => true, :body => "Auth=MYTOKEN"))
+
+    described_class.new(connection).login('me@example.com', 'password')
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: google_analytics_feeds
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Roland Swingler
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-08-31 00:00:00 Z
+date: 2012-10-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   requirement: &id001 !ruby/object:Gem::Requirement 
@@ -77,15 +77,14 @@ dependencies:
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version 
-        hash: 31
+        hash: 3
         segments: 
-        - 3
-        - 12
-        version: "3.12"
+        - 0
+        version: "0"
   version_requirements: *id005
-  name: rdoc
+  name: yard
   prerelease: false
   type: :development
 - !ruby/object:Gem::Dependency 
@@ -129,6 +128,8 @@ extra_rdoc_files:
 files: 
 - .document
 - .rspec
+- .travis.yml
+- .yardopts
 - Gemfile
 - LICENSE.txt
 - README.rdoc
@@ -136,9 +137,9 @@ files:
 - VERSION
 - google_analytics_feeds.gemspec
 - lib/google_analytics_feeds.rb
-- lib/sample.rb
 - spec/google_analytics_feeds_spec.rb
 - spec/request_spec.rb
+- spec/session_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/knaveofdiamonds/google_analytics_feeds
 licenses: 

data/lib/sample.rb

@@ -1,15 +0,0 @@
-require File.dirname(__FILE__) + "/google_analytics_feeds" 
-
-class LoggingRowHandler < GoogleAnalyticsFeeds::RowHandler
-  def row(r)
-    puts r.inspect
-  end
-
-  def end_rows
-    puts "Done!"
-  end
-end
-
-File.open("/home/roland/gaout2.xml") do |fh|
-  GoogleAnalyticsFeeds.parse_data_rows(fh, LoggingRowHandler)
-end