/lib/gattica/engine.rb
Ruby | 283 lines | 152 code | 34 blank | 97 comment | 27 complexity | 1f9f528d156c2fb5f93b92f6d2d95332 MD5 | raw file
- module Gattica
- class Engine
- attr_reader :user
- attr_accessor :profile_id, :token
- # Initialize Gattica using username/password or token.
- #
- # == Options:
- # To change the defaults see link:settings.rb
- # +:debug+:: Send debug info to the logger (default is false)
- # +:email+:: Your email/login for Google Analytics
- # +:headers+:: Add additional HTTP headers (default is {} )
- # +:logger+:: Logger to use (default is STDOUT)
- # +:password+:: Your password for Google Analytics
- # +:profile_id+:: Use this Google Analytics profile_id (default is nil)
- # +:timeout+:: Set Net:HTTP timeout in seconds (default is 300)
- # +:token+:: Use an authentication token you received before
- def initialize(options={})
- @options = Settings::DEFAULT_OPTIONS.merge(options)
- handle_init_options(@options)
- create_http_connection()
- check_init_auth_requirements()
- # 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
- # Returns the list of accounts the user has access to. A user may have
- # multiple accounts on Google Analytics and each account may have multiple
- # profiles. You need the profile_id in order to get info from GA. If you
- # 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({:email => 'johndoe@google.com', :password => 'password'})
- # ga.accounts
- # # you parse through the accounts to find the profile_id you need
- # ga.profile_id = 12345678
- # # now you can perform a regular search, see Gattica::Engine#get
- #
- # If you pass in a profile id when you instantiate Gattica::Search then you won't need to
- # get the accounts and find a profile_id - you apparently already know it!
- #
- # See Gattica::Engine#get to see how to get some data.
- def accounts
- # if we haven't retrieved the user's accounts yet, get them now and save them
- if @user_accounts.nil?
- data = request_default_account_feed
- xml = Hpricot(data)
- @user_accounts = xml.search(:entry).collect { |entry| Account.new(entry) }
- end
- return @user_accounts
- end
- # Returns the list of segments available to the authenticated user.
- #
- # == Usage
- # ga = Gattica.new({:email => 'johndoe@google.com', :password => 'password'})
- # ga.segments # Look up segment id
- # my_gaid = 'gaid::-5' # Non-paid Search Traffic
- # ga.profile_id = 12345678 # Set our profile ID
- #
- # gs.get({ :start_date => '2008-01-01',
- # :end_date => '2008-02-01',
- # :dimensions => 'month',
- # :metrics => 'views',
- # :segment => my_gaid })
- def segments
- if @user_segments.nil?
- data = request_default_account_feed
- xml = Hpricot(data)
- @user_segments = xml.search("dxp:segment").collect { |s| Segment.new(s) }
- end
- return @user_segments
- end
- # This is the method that performs the actual request to get data.
- #
- # == Usage
- #
- # 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',
- # :metrics => 'pageviews',
- # :sort => 'pageviews',
- # :filters => ['browser == Firefox']})
- #
- # == Input
- #
- # When calling +get+ you'll pass in a hash of options. For a description of what these mean to
- # Google Analytics, see http://code.google.com/apis/analytics/docs
- #
- # Required values are:
- #
- # * +start_date+ => Beginning of the date range to search within
- # * +end_date+ => End of the date range to search within
- #
- # Optional values are:
- #
- # * +dimensions+ => an array of GA dimensions (without the ga: prefix)
- # * +metrics+ => an array of GA metrics (without the ga: prefix)
- # * +filter+ => an array of GA dimensions/metrics you want to filter by (without the ga: prefix)
- # * +sort+ => an array of GA dimensions/metrics you want to sort by (without the ga: prefix)
- #
- # == Exceptions
- #
- # If a user doesn't have access to the +profile_id+ you specified, you'll receive an error.
- # Likewise, if you attempt to access a dimension or metric that doesn't exist, you'll get an
- # error back from Google Analytics telling you so.
- def get(args={})
- args = validate_and_clean(Settings::DEFAULT_ARGS.merge(args))
- query_string = build_query_string(args,@profile_id)
- @logger.debug(query_string) if @debug
- data = do_http_get("/analytics/feeds/data?#{query_string}")
- #data = do_http_get("/analytics/feeds/data?ids=ga%3A915568&metrics=ga%3Avisits&segment=gaid%3A%3A-7&start-date=2010-03-29&end-date=2010-03-29&max-results=50")
- return DataSet.new(Hpricot.XML(data))
- 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 so we override the default writer (note that you need to set
- # @token with self.token= instead of @token=)
- def token=(token)
- @token = token
- set_http_headers
- end
- ######################################################################
- private
- # Gets the default account feed from Google
- def request_default_account_feed
- if @default_account_feed.nil?
- @default_account_feed = do_http_get('/analytics/feeds/accounts/default')
- end
- return @default_account_feed
- end
- # Does the work of making HTTP calls and then going through a suite of tests on the response to make
- # sure it's valid and not an error
- def do_http_get(query_string)
- response, data = @http.get(query_string, @headers)
- # error checking
- if response.code != '200'
- case response.code
- when '400'
- raise GatticaError::AnalyticsError, response.body + " (status code: #{response.code})"
- when '401'
- raise GatticaError::InvalidToken, "Your authorization token is invalid or has expired (status code: #{response.code})"
- else # some other unknown error
- raise GatticaError::UnknownAnalyticsError, response.body + " (status code: #{response.code})"
- end
- end
- return data
- end
- # 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}"
- @headers['GData-Version']= '2'
- 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]}"
- if (start_index = args[:start_index].to_i) > 0
- output += "&start-index=#{start_index}"
- end
- unless args[:dimensions].empty?
- output += '&dimensions=' + args[:dimensions].collect do |dimension|
- "ga:#{dimension}"
- end.join(',')
- end
- unless args[:metrics].empty?
- output += '&metrics=' + args[:metrics].collect do |metric|
- "ga:#{metric}"
- end.join(',')
- end
- unless args[:sort].empty?
- output += '&sort=' + args[:sort].collect do |sort|
- sort[0..0] == '-' ? "-ga:#{sort[1..-1]}" : "ga:#{sort}" # if the first character is a dash, move it before the ga:
- end.join(',')
- end
- unless args[:segment].nil?
- output += "&segment=#{args[:segment]}"
- end
- unless args[:max_results].nil?
- output += "&max-results=#{args[:max_results]}"
- end
- # TODO: update so that in regular expression filters (=~ and !~), any initial special characters in the regular expression aren't also picked up as part of the operator (doesn't cause a problem, but just feels dirty)
- unless args[:filters].empty? # filters are a little more complicated because they can have all kinds of modifiers
- output += '&filters=' + args[:filters].collect do |filter|
- match, name, operator, expression = *filter.match(/^(\w*)\s*([=!<>~@]*)\s*(.*)$/) # splat the resulting Match object to pull out the parts automatically
- unless name.empty? || operator.empty? || expression.empty? # make sure they all contain something
- "ga:#{name}#{CGI::escape(operator.gsub(/ /,''))}#{CGI::escape(expression)}" # remove any whitespace from the operator before output
- else
- raise GatticaError::InvalidFilter, "The filter '#{filter}' is invalid. Filters should look like 'browser == Firefox' or 'browser==Firefox'"
- end
- end.join(';')
- end
- return output
- end
- # Validates that the args passed to +get+ are valid
- def validate_and_clean(args)
- raise GatticaError::MissingStartDate, ':start_date is required' if args[:start_date].nil? || args[:start_date].empty?
- raise GatticaError::MissingEndDate, ':end_date is required' if args[:end_date].nil? || args[:end_date].empty?
- raise GatticaError::TooManyDimensions, 'You can only have a maximum of 7 dimensions' if args[:dimensions] && (args[:dimensions].is_a?(Array) && args[:dimensions].length > 7)
- raise GatticaError::TooManyMetrics, 'You can only have a maximum of 10 metrics' if args[:metrics] && (args[:metrics].is_a?(Array) && args[:metrics].length > 10)
- possible = args[:dimensions] + args[:metrics]
- # make sure that the user is only trying to sort fields that they've previously included with dimensions and metrics
- if args[:sort]
- missing = args[:sort].find_all do |arg|
- !possible.include? arg.gsub(/^-/,'') # remove possible minuses from any sort params
- end
- unless missing.empty?
- raise GatticaError::InvalidSort, "You are trying to sort by fields that are not in the available dimensions or metrics: #{missing.join(', ')}"
- end
- end
- # make sure that the user is only trying to filter fields that are in dimensions or metrics
- if args[:filters]
- missing = args[:filters].find_all do |arg|
- !possible.include? arg.match(/^\w*/).to_s # get the name of the filter and compare
- end
- unless missing.empty?
- raise GatticaError::InvalidSort, "You are trying to filter by fields that are not in the available dimensions or metrics: #{missing.join(', ')}"
- end
- end
- return args
- end
- def create_http_connection
- port = Settings::USE_SSL ? Settings::SSL_PORT : Settings::NON_SSL_PORT
- @http = Net::HTTP.new(Settings::SERVER, port)
- @http.use_ssl = Settings::USE_SSL
- @http.set_debug_output $stdout if @options[:debug]
- @http.read_timeout = @options[:timeout] if @options[:timeout]
- end
- # Sets instance variables from options given during initialization and
- def handle_init_options(options)
- @logger = options[:logger]
- @profile_id = options[:profile_id]
- @user_accounts = nil # filled in later if the user ever calls Gattica::Engine#accounts
- @user_segments = nil
- @headers = { }.merge(options[:headers]) # headers used for any HTTP requests (Google requires a special 'Authorization' header which is set any time @token is set)
- @default_account_feed = nil
- end
- # If the authorization is a email and password then create User objects
- # or if it's a previous token, use that. Else, raise exception.
- def check_init_auth_requirements
- if @options[:token].to_s.length > 200 # Not sure actual required length, but mine's 267
- self.token = @options[:token]
- elsif @options[:email] && @options[:password]
- @user = User.new(@options[:email], @options[:password])
- @auth = Auth.new(@http, user)
- self.token = @auth.tokens[:auth]
- else
- raise GatticaError::NoLoginOrToken, 'An email and password or an authentication token is required to initialize Gattica.'
- end
- end
- end
- end