cannikin-gattica 0.1.4 → 0.2.0

data/History.txt

@@ -1,3 +1,10 @@
+== 0.2.0 / 2009-04-27
+  * Changed initialization format: pass a hash of options rather than individual email, password and profile_id
+  * Can initialize with a valid token and use that instead of requiring email/password each time
+  * Can initialize with your own logger object instead of having to use the default (useful if you're using with Rails, initialize with RAILS_DEFAULT_LOGGER)
+  * Show error if token is invalid or expired (Google returns a 401 on any HTTP call)
+  * Started tests
+
 == 0.1.4 / 2009-04-22
   * Another attempt at getting the gem to build on github
 

data/README.rdoc

@@ -11,25 +11,23 @@ When you want to require, you just use 'gattica' as the gem name:
   require 'gattica'
 
 = Introduction
+It's a good idea to familiarize yourself with the Google API docs: http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
+  
+In particular there are some very specific combinations of Metrics and Dimensions that
+you are restricted to and those are explained in this document: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html
+
+See examples/example.rb for some code that should work automatically if you replace the email/password with your own
+
 There are generally three steps to getting info from the GA API:
 
 1. Authenticate
 2. Get a profile id
 3. Get the data you really want
 
-It's a good idea to familiarize yourself with the Google API docs:
-
-  http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
-  
-In particular there are some very specific combinations of Metrics and Dimensions that
-you are restricted to and those are explained in this document:
-
-  http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html
-
 = Usage
 This library does all three. A typical transaction will look like this:
 
- gs = Gattica.new('johndoe@google.com','password',123456)
+ gs = Gattica.new({:email => 'johndoe@google.com', :password => 'password', profile_id => 123456})
  results = gs.get({ :start_date => '2008-01-01', 
                     :end_date => '2008-02-01', 
                     :dimensions => 'browser', 
@@ -45,7 +43,7 @@ page views.
 
 If you don't know the profile_id you want to get data for, call +accounts+
 
- gs = Gattica.new('johndoe@google.com','password')
+ gs = Gattica.new({:email => 'johndoe@google.com', :password => 'password'})
  accounts = gs.accounts
 
 This returns all of the accounts and profiles that the user has access to. Note that if you
@@ -59,9 +57,7 @@ use this method to get profiles, you need to manually set the profile before you
                     :sort => '-pageviews'})
                     
 When you put in the names for the dimensions and metrics you want, refer to this doc for the 
-available names:
-
-  http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html
+available names: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html
   
 Note that you do *not* use the 'ga:' prefix when you tell Gattica which ones you want. Gattica
 adds that for you automatically.
@@ -74,7 +70,35 @@ also pass in single values as arrays too, if you wish):
                      :dimensions => ['browser','browserVersion'], 
                      :metrics => ['pageviews','visits'], 
                      :sort => ['-pageviews']})
-                      
+                     
+== Notes on Authentication
+=== Authentication Token
+Google recommends not re-authenticating each time you do a request against the API. To accomplish
+this you should save the authorization token you receive from Google and use that for future 
+requests:
+
+  ga.token => 'DSasdf94...' (some huge long string)
+  
+You can now initialize Gattica with this token for future requests:
+
+  ga = Gattica.new({:token => 'DSasdf94...'})
+  
+(You enter the full token, of course). I'm not sure how long a token from the Google's ClientLogin
+system remains active, but if/when I do I'll add that to the docs here.
+
+=== Headers
+Google expects a special header in all HTTP requests called 'Authorization'. This contains your
+token:
+
+  Authorization = GoogleLogin auth=DSasdf94...
+
+This header is generated automatically. If you have your own headers you'd like to add, you can 
+pass them in when you initialize:
+
+  ga = Gattica.new({:token => 'DSasdf94...', :headers => {'My-Special-Header':'my_custom_value'}})
+  
+And they'll be sent with every request you make.
+  
 = Output
 When Gattica was originally created it was intended to take the data returned and put it into
 Excel for someone else to crunch through the numbers. Thus, Gattica has great built-in support
@@ -122,9 +146,9 @@ the API what number to begin at and it will return the next 1000. Gattica does n
 support this, but it's in the plan for the very next version.
 
 The GA API support filtering, so you can say things like "only show me the pageviews for pages
-whose URL meets the regular expression ^/saf.*?/$". Gattica can pass in filters, but you'll need
-to know how to format them correctly (refer to the GA API), it won't let you do any kind of pretty
-syntax and convert it for you. I plan to add this soon.
+whose URL meets the regular expression ^/saf.*?/$". Support for filters have begun, but according
+to one report, the DataSet object that returns doesn't parse the results correctly. So for now,
+avoid using filters.
 
 = The Future
 A couple of things I have planned:

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "gattica"
+    gemspec.summary = "Gattica is a Ruby library for extracting data from the Google Analytics API."
+    gemspec.email = "cannikinn@gmail.com"
+    gemspec.homepage = "http://github.com/cannikin/gattica"
+    gemspec.description = "Gattica is a Ruby library for extracting data from the Google Analytics API."
+    gemspec.authors = ["Rob Cameron"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = false
+end

data/VERSION.yml

@@ -1,4 +1,4 @@
----
+--- 
 :major: 0
-:minor: 1
-:patch: 4
+:minor: 2
+:patch: 0

data/examples/example.rb

@@ -1,7 +1,10 @@
 require '../lib/gattica'
 
-# authenticate with the API
-ga = Gattica.new('username@gmail.com','password')
+# authenticate with the API via email/password
+ga = Gattica.new({:email => 'username@gmail.com', :password => 'password'})
+
+# or, initialize via a pre-existing token (does not authenticate, but will throw an error on subsequent calls [like ga.accounts] if the token is invalid)
+# ga = Gattica.new({:token => 'DQAAAJYAAACN-JMelka5I0Fs-T6lF53eUSfUooeHgcKc1iEdc0wkDS3w8GaXY7LjuUB_4vmzDB94HpScrULiweW_xQsU8yyUgdInDIX7ZnHm8_o0knf6FWSR90IoAZGsphpqteOjZ3O0NlNt603GgG7ylvGWRSeHl1ybD38nysMsKJR-dj0LYgIyPMvtgXLrqr_20oTTEExYbrDSg5_q84PkoLHUcODZ' })
 
 # get the list of accounts you have access to with that username and password
 accounts = ga.accounts
@@ -11,6 +14,8 @@ accounts = ga.accounts
 # property you're most used to seeing in GA, looks like UA123456-1)
 ga.profile_id = accounts.first.profile_id
 
+# puts ga.token
+
 # now get the number of page views by browser for Janurary 2009
 # note that as of right now, Gattica does not support filtering
 data = ga.get({ :start_date => '2009-01-01', 

data/lib/gattica.rb

@@ -20,57 +20,22 @@ require 'gattica/data_point'
 
 # Gattica is a Ruby library for talking to the Google Analytics API.
 #
-# = Introduction
-# There are generally three steps to getting info from the GA API:
-# 
-# 1. Authenticate
-# 2. Get a profile id
-# 3. Get the data you really want
-# 
-# = Usage
-# This library does all three. A typical transaction will look like this:
-# 
-#  gs = Gattica.new('johndoe@google.com','password',123456)
-#  results = gs.get({ :start_date => '2008-01-01', 
-#                     :end_date => '2008-02-01', 
-#                     :dimensions => 'browser', 
-#                     :metrics => 'pageviews', 
-#                     :sort => 'pageviews'})
-# 
-# So we instantiate a copy of Gattica and pass it a Google Account email address and password.
-# The third parameter is the profile_id that we want to access data for. (If you don't know what
-# your profile_id is [and you probably don't since GA doesn't tell you except through this API]
-# then check out Gattica::Engine#accounts).
-# 
-# Then we call +get+ with the parameters we want to shape our data with. In this case we want
-# total page views, broken down by browser, from Jan 1 2008 to Feb 1 2008, sorted by page views.
-# 
-# If you don't know the profile_id you want to get data for, call +accounts+
-# 
-#  gs = Gattica.new('johndoe@google.com','password')
-#  accounts = gs.accounts
-# 
-# This returns all of the accounts and profiles that the user has access to. Note that if you
-# use this method to get profiles, you need to manually set the profile before you can call +get+
-# 
-#  gs.profile_id = 123456
-#  results = gs.get({ :start_date => '2008-01-01', 
-#                     :end_date => '2008-02-01', 
-#                     :dimensions => 'browser', 
-#                     :metrics => 'pageviews', 
-#                     :sort => 'pageviews'})
-
+# Please see the README for usage docs.
 
 module Gattica
   
-  VERSION = '0.1.4'
-  LOGGER = Logger.new(STDOUT)
-
+  VERSION = '0.2.0'
+  
+  # Creates a new instance of Gattica::Engine and gets us going. Please see the README for usage docs.
+  #
+  #   ga = Gattica.new({:email => 'anonymous@anon.com', :password => 'password, :profile_id => 123456 })
+  
   def self.new(*args)
     Engine.new(*args)
   end
   
-  # The real meat of Gattica, deals with talking to GA, returning and parsing results.
+  # The real meat of Gattica, deals with talking to GA, returning and parsing results. You automatically
+  # get an instance of this when you go Gattica.new()
   
   class Engine
     
@@ -78,33 +43,48 @@ module Gattica
     PORT = 443
     SECURE = true
     DEFAULT_ARGS = { :start_date => nil, :end_date => nil, :dimensions => [], :metrics => [], :filters => [], :sort => [] }
+    DEFAULT_OPTIONS = { :email => nil, :password => nil, :token => nil, :profile_id => nil, :debug => false, :headers => {}, :logger => Logger.new(STDOUT) }
     
-    attr_reader :user, :token
-    attr_accessor :profile_id
+    attr_reader :user
+    attr_accessor :profile_id, :token
     
     # Create a user, and get them authorized.
-    # If you're making a web app you're going to want to save the token that's returned by this
-    # method so that you can use it later (without having to re-authenticate the user each time)
+    # If you're making a web app you're going to want to save the token that's retrieved by Gattica
+    # so that you can use it later (Google recommends not re-authenticating the user for each and every request)
     #
-    #   ga = Gattica.new('johndoe@google.com','password',123456)
+    #   ga = Gattica.new({:email => 'johndoe@google.com', :password => 'password', :profile_id => 123456})
     #   ga.token => 'DW9N00wenl23R0...' (really long string)
+    #
+    # Or if you already have the token (because you authenticated previously and now want to reuse that session):
+    #
+    #   ga = Gattica.new({:token => '23ohda09hw...', :profile_id => 123456})
     
-    def initialize(email,password,profile_id=0,debug=false)
-      LOGGER.datetime_format = '' if LOGGER.respond_to? 'datetime_format'
+    def initialize(options={})
+      @options = DEFAULT_OPTIONS.merge(options)
+      @logger = @options[:logger]
       
-      @profile_id = profile_id
-      @user_accounts = nil
+      @profile_id = @options[:profile_id]     # if you don't include the profile_id now, you'll have to set it manually later via Gattica::Engine#profile_id=
+      @user_accounts = nil                    # filled in later if the user ever calls Gattica::Engine#accounts
+      @headers = {}                           # headers used for any HTTP requests (Google requires a special 'Authorization' header)
       
       # save an http connection for everyone to use
       @http = Net::HTTP.new(SERVER, PORT)
       @http.use_ssl = SECURE
-      @http.set_debug_output $stdout if debug
+      @http.set_debug_output $stdout if @options[:debug]
       
-      # create a user and authenticate them
-      @user = User.new(email, password)
-      @auth = Auth.new(@http, user, { :source => 'active-gattica-0.1' }, { 'User-Agent' => 'ruby 1.8.6 (2008-03-03 patchlevel 114) [universal-darwin9.0] Net::HTTP' })
-      @token = @auth.tokens[:auth]
-      @headers = { 'Authorization' => "GoogleLogin auth=#{@token}" }
+      # authenticate
+      if @options[:email] && @options[:password]      # email and password: authenticate and get a token from Google's ClientLogin
+        @user = User.new(@options[:email], @options[:password])
+        @auth = Auth.new(@http, user, { :source => 'gattica-'+VERSION }, { 'User-Agent' => 'Ruby Net::HTTP' })
+        self.token = @auth.tokens[:auth]
+      elsif @options[:token]                          # use an existing token (this also sets the headers for any HTTP requests we make)
+        self.token = @options[:token]
+      else                                            # no login or token, you can't do anything
+        raise GatticaError::NoLoginOrToken, 'You must provide an email and password, or authentication token'
+      end
+
+      # the user can provide their own additional headers - merge them into the ones that Gattica requires
+      @headers = @headers.merge(@options[:headers])
       
       # TODO: check that the user has access to the specified profile and show an error here rather than wait for Google to respond with a message
     end
@@ -115,7 +95,7 @@ module Gattica
     # don't know the profile_id then use this method to get a list of all them. Then set the profile_id of your
     # instance and you can make regular calls from then on.
     #
-    #   ga = Gattica.new('johndoe@google.com','password')
+    #   ga = Gattica.new({:email => 'johndoe@google.com', :password => 'password'})
     #   ga.get_accounts
     #   # you parse through the accounts to find the profile_id you need
     #   ga.profile_id = 12345678
@@ -129,7 +109,11 @@ module Gattica
     def accounts
       # if we haven't retrieved the user's accounts yet, get them now and save them
       if @accts.nil?
+        # TODO: move these calls into their own method so we can encapsulate all the errors in one place
         response, data = @http.get('/analytics/feeds/accounts/default', @headers)
+        if response.code == '401'
+          raise GatticaError::InvalidToken, 'The token you have provided is invalid or has expired'
+        end
         xml = Hpricot(data)
         @user_accounts = xml.search(:entry).collect { |entry| Account.new(entry) }
       end
@@ -141,7 +125,7 @@ module Gattica
     #
     # == Usage
     #
-    #   gs = Gattica.new('johndoe@google.com','password',123456)
+    #   gs = Gattica.new({:email => 'johndoe@google.com', :password => 'password', :profile_id => 123456})
     #   gs.get({ :start_date => '2008-01-01', 
     #            :end_date => '2008-02-01', 
     #            :dimensions => 'browser', 
@@ -174,8 +158,12 @@ module Gattica
     def get(args={})
       args = validate_and_clean(DEFAULT_ARGS.merge(args))
       query_string = build_query_string(args,@profile_id)
-        LOGGER.debug(query_string)
+        @logger.debug(query_string)
+      # TODO: move these calls into their own method so we can encapsulate all the errors in one place
       response, data = @http.get("/analytics/feeds/data?#{query_string}", @headers)
+      if response.code == '401'
+        raise GatticaError::InvalidToken, 'The token you have provided is invalid or has expired'
+      end
       begin
         response.value
       rescue Net::HTTPServerException => e
@@ -185,7 +173,24 @@ module Gattica
     end
     
     
+    # Since google wants the token to appear in any HTTP call's header, we have to set that header
+    # again any time @token is changed
+    
+    def token=(token)
+      @token = token
+      set_http_headers
+    end
+    
+    
     private
+    
+    # Sets up the HTTP headers that Google expects (this is called any time @token is set either by Gattica
+    # or manually by the user since the header must include the token)
+    def set_http_headers
+      @headers['Authorization'] = "GoogleLogin auth=#{@token}"
+    end
+    
+    
     # Creates a valid query string for GA
     def build_query_string(args,profile)
       output = "ids=ga:#{profile}&start-date=#{args[:start_date]}&end-date=#{args[:end_date]}"

data/lib/gattica/exceptions.rb

@@ -4,6 +4,8 @@ module GatticaError
   class InvalidPassword < StandardError; end;
   # authentication errors
   class CouldNotAuthenticate < StandardError; end;
+  class NoLoginOrToken < StandardError; end;
+  class InvalidToken < StandardError; end;
   # profile errors
   class InvalidProfileId < StandardError; end;
   # search errors

data/test/helper.rb

@@ -4,7 +4,7 @@ require 'rubygems'
 require 'test/unit'
 require 'mocha'
  
-include Gattica
+# include Gattica
  
 def fixture(name)
   File.read(File.join(File.dirname(__FILE__), 'fixtures', name))

data/test/{test_sample.rb → test_auth.rb}

@@ -1,13 +1,12 @@
 require File.dirname(__FILE__) + '/helper'
  
-class TestActor < Test::Unit::TestCase
+class TestAuth < Test::Unit::TestCase
   def setup
     
   end
   
-  # from_string
-  
   def test_truth
     assert true
   end
-end
+  
+end

data/test/test_engine.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + '/helper'
+ 
+class TestEngine < Test::Unit::TestCase
+  def setup
+    
+  end
+  
+  def test_initialization
+    assert Gattica.new({:email => 'anonymous@anon.com', :password => 'none'}) # you can initialize with a potentially invalid email and password
+    assert Gattica.new({:token => 'test'})                                    # you can initialize with a potentially invalid token
+    assert_raise GatticaError::NoLoginOrToken do Gattica.new() end            # but, you must initialize with one or the other
+  end
+  
+end

data/test/test_user.rb

@@ -0,0 +1,24 @@
+require File.dirname(__FILE__) + '/helper'
+ 
+class TestUser < Test::Unit::TestCase
+  def setup
+    
+  end
+  
+  def test_can_create_user
+    assert Gattica::User.new('anonymous@anon.com','none')
+  end
+  
+  def test_invalid_email
+    assert_raise GatticaError::InvalidEmail do Gattica::User.new('','') end
+    assert_raise ArgumentError do Gattica::User.new('') end
+    assert_raise GatticaError::InvalidEmail do Gattica::User.new('anonymous','none') end
+    assert_raise GatticaError::InvalidEmail do Gattica::User.new('anonymous@asdfcom','none') end
+  end
+    
+  def test_invalid_password
+    assert_raise GatticaError::InvalidPassword do Gattica::User.new('anonymous@anon.com','') end
+    assert_raise ArgumentError do Gattica::User.new('anonymous@anon.com') end
+  end
+  
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cannikin-gattica
 version: !ruby/object:Gem::Version 
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors: 
 - Rob Cameron
@@ -9,34 +9,26 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-22 00:00:00 -07:00
+date: 2009-04-27 00:00:00 -07:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: hpricot
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 0.8.1
-    version: 
+dependencies: []
+
 description: Gattica is a Ruby library for extracting data from the Google Analytics API.
 email: cannikinn@gmail.com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
 files: 
 - History.txt
-- README.rdoc
 - LICENSE
+- README.rdoc
+- Rakefile
 - VERSION.yml
 - examples/example.rb
-- lib/gattica
 - lib/gattica.rb
 - lib/gattica/account.rb
 - lib/gattica/auth.rb
@@ -48,12 +40,13 @@ files:
 - lib/gattica/user.rb
 - test/helper.rb
 - test/suite.rb
-- test/test_sample.rb
+- test/test_auth.rb
+- test/test_engine.rb
+- test/test_user.rb
 has_rdoc: true
 homepage: http://github.com/cannikin/gattica
 post_install_message: 
 rdoc_options: 
-- --inline-source
 - --charset=UTF-8
 require_paths: 
 - lib
@@ -69,13 +62,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version 
       version: "0"
   version: 
-requirements: 
-- A Google Analytics Account
-- One or more Profiles that are being tracked in your GA account
+requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: Gattica is a Ruby library for extracting data from the Google Analytics API.
-test_files: []
-
+test_files: 
+- test/helper.rb
+- test/suite.rb
+- test/test_auth.rb
+- test/test_engine.rb
+- test/test_user.rb
+- examples/example.rb