ariadna 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ariadna.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,19 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+end
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jorge Alvarez
+
+MIT License
+
+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/README.md

@@ -0,0 +1,138 @@
+# Ariadna
+
+Google Analytics API wrapper.
+
+It uses Oauth2 as authorization
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+gem 'ariadna'
+
+And then execute:
+
+$ bundle
+
+Or install it yourself as:
+
+$ gem install ariadna
+
+## Usage
+
+Create a new connexion with your Oauth2 access token
+
+```ruby
+  analytics = Ariadna::Analytics.new(access_token)
+```
+
+Get a list of all accounts available
+
+```ruby
+  accounts    = analytics.accounts
+```
+
+Get a list of all web properties available for an account
+
+```ruby
+  properties = accounts.first.properties.all
+```
+
+Get a list of all profiles available for a web property
+
+```ruby
+  profiles    = properties.first.profiles.all
+```
+
+Create a query with your metrics and dimensions
+
+```ruby
+  results  = profile.results.select(
+        :metrics    => [:visits, :bounces, :timeOnSite],
+        :dimensions => [:country]
+      )
+      .where(
+        :start_date => Date.today,
+        :end_date   => 2.months.ago,
+        :browser    => "==Firefox"
+      )
+      .limit(100)
+      .offset(40)
+      .order([:visits, :bounces])
+      .all
+```
+
+All the metrics and dimensions returned by the query are mapped into attributes.
+
+```ruby
+  @results.each do |result|
+    puts result.visits
+    puts result.bounces
+    puts result.timeonsite
+    puts result.country
+  end
+```
+
+### Create a connexion
+
+  Ariadna::Analytics.new(access_token, proxy_settings, refresh_token_data)
+
+  There are three possible params:
+
+  access_token (mandatory): an oauth2 access token 
+
+  proxy_settings (optional): a hash containing your proxy options
+
+  refresh_token_data (optional): a hash with information about your app so access_token can be renewed automatically in case it is expired.
+
+```ruby
+  analytics = Ariadna::Analytics.new(
+    access_token,
+    { proxy_host: 'proxy.yourproxy.com',
+      proxy_port: 8080,
+      proxy_user: 'username',
+      proxy_pass: 'password'
+     },
+    # Google access tokens are short term so chances are you are going to need to refresh them
+    { refresh_token: analytics_refresh_token,
+      client_id: 'apps.googleusercontent.com',
+      client_secret: 'client_secret',
+      current_user:  current_user
+    }
+  )
+```
+
+### Access token
+
+Ariadna is agnostic about the way you get your Oauth2 access token.
+
+For the development of this gem I've been using [Omiauth](https://github.com/intridea/omniauth) with the [Google Oauth2 strategy](https://github.com/zquestz/omniauth-google-oauth2)
+
+```ruby
+gem 'omniauth'
+
+gem 'omniauth-google-oauth2'
+```
+
+Google Oauth2 tokens have a very short life.  To make things easy if the connexion gives a 401 error and there is a refresh token passed as a param Ariadna will try to get a new access token from Google and store it in the curren user info calling update_access_token_from_google.  If you want to use this feature you must create a method in your user model that saves this token.
+
+```ruby
+def update_access_token_from_google(new_token)
+  update_attribute(:google_oauth2_token, new_token)
+end
+```
+
+It is obviously out of the scope of this gem to update tokens but it is definetly something that will make your life easier.
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Contributors
+
+* Jorge Alvarez [http://www.alvareznavarro.es](http://www.alvareznavarro.es/?utm_source=github&utm_medium=gem&utm_campaign=ariadna)

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/ariadna.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/ariadna/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Jorge Alvarez"]
+  gem.email         = ["jorge@alvareznavarro.es"]
+  gem.description   = %q{Google Analytics A.P.I. V3 wrapper with oauth2}
+  gem.summary       = %q{Google Analytics A.P.I. V3 wrapper with oauth2}
+  gem.homepage      = "https://github.com/jorgegorka/ariadna"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "ariadna"
+  gem.require_paths = ["lib"]
+  gem.version       = Ariadna::VERSION
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "guard-rspec"
+end

data/lib/ariadna/account.rb

@@ -0,0 +1,45 @@
+module Ariadna
+  class Account
+
+    class << self; 
+      attr_reader :url 
+      attr_accessor :owner
+    end
+
+    #attr_reader :id, :link, :name, :properties_url
+
+    @url = "https://www.googleapis.com/analytics/v3/management/accounts"
+    
+    def initialize(item)
+      item.each do |k,v|
+        instance_variable_set("@#{k}", v)
+      end
+    end
+
+    def self.all
+      @accounts ||= create_accounts
+    end
+
+    def properties
+      Delegator.new(WebProperty, self)
+    end
+
+    private
+
+    def self.create_accounts
+      accounts = Ariadna.connexion.get_url(self.url)
+      if (accounts["totalResults"].to_i > 0)
+        create_attributes(accounts["items"])
+        accounts["items"].map do |account|
+          Account.new(account)
+        end
+      end
+    end
+
+    def self.create_attributes(items)
+      items.first.each do |k,v|
+        attr_reader k.to_sym
+      end
+    end
+  end
+end

data/lib/ariadna/analytics.rb

@@ -0,0 +1,11 @@
+module Ariadna
+  class Analytics
+    def initialize(token, proxy_options=nil, refresh_info=nil)
+      Ariadna.connexion = Connexion.new(token, proxy_options, refresh_info)
+    end
+
+    def accounts
+      Delegator.new(Account, self)
+    end    
+  end
+end

data/lib/ariadna/connexion.rb

@@ -0,0 +1,118 @@
+require 'net/http'
+
+module Ariadna
+  class Connexion
+
+    def initialize(token, proxy_options, refresh_info)
+      @token = token
+      extract_proxy_options(proxy_options) if proxy_options
+      extract_refresh_info(refresh_info) if refresh_info
+    end
+
+    # get url and try to refresh token if Unauthorized
+    def get_url(url, params=nil)
+      uri     = URI(url)
+      headers = Hash.new
+      resp    = get_conn(uri)
+
+      case resp
+      # response is ok
+      when Net::HTTPSuccess, Net::HTTPRedirection
+        parse_response(resp)
+      # if we have a refresh token we can ask for a new access token
+      when Net::HTTPUnauthorized
+        get_url(url) if @refresh_token and get_access_token     
+      when Net::HTTPBadRequest
+        raise Error.new(parse_response(resp))
+      when Net::HTTPNotFound
+        ["not found", uri]
+      else
+        resp.value
+      end
+
+    end
+
+    private
+
+    def extract_proxy_options(proxy_options)
+      return unless proxy_options.present?
+      @use_proxy  = true
+      @proxy_host = proxy_options[:proxy_host]
+      @proxy_port = proxy_options[:proxy_port]
+      @proxy_user = proxy_options[:proxy_user]
+      @proxy_pass = proxy_options[:proxy_pass]
+    end
+
+    def extract_refresh_info(refresh_info)
+      return unless refresh_info.present?
+      @refresh_token = refresh_info[:refresh_token]
+      @client_id     = refresh_info[:client_id]
+      @client_secret = refresh_info[:client_secret]
+      @current_user  = refresh_info[:current_user]
+    end
+
+    # refresh access token as google access tokens have short term live
+    def get_access_token
+      uri = URI("https://accounts.google.com/o/oauth2/token")
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req.set_form_data(
+        'client_id'     => @client_id, 
+        'client_secret' => @client_secret,
+        'refresh_token' => @refresh_token,
+        'grant_type'    => 'refresh_token'
+      )
+      if @use_proxy 
+        conn = Net::HTTP::Proxy(@proxy_host, @proxy_port, @proxy_user, @proxy_pass).start(uri.hostname, uri.port) {|http|
+          http.request(req)
+        }
+      else 
+        # conn = Net::HTTP.new(uri.host, uri.port)
+        # conn.request(req) 
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.port == 443
+        conn = http.start { |http| http.request(req) }
+        conn
+      end
+
+      case conn
+      # response is ok
+      when Net::HTTPSuccess, Net::HTTPRedirection
+        # use the new access token 
+        refresh_info              = parse_response(conn)
+        @token                    = refresh_info["access_token"]
+        @current_user.update_access_token_from_google(@token)
+        return true
+      # if not allowed revoke access
+      when Net::HTTPUnauthorized
+        @refresh_token = nil
+      else
+        conn
+      end
+      return false
+    end
+
+    def get_conn(uri)
+      req                  = Net::HTTP::Get.new(uri.request_uri)
+      req["Authorization"] = "Bearer #{@token}"
+      if @use_proxy  
+        res = Net::HTTP::Proxy(@proxy_host, @proxy_port, @proxy_user, @proxy_pass).start(uri.hostname, uri.port) {|http|
+          http.request(req)
+        }
+        res
+      else        
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.port == 443
+        conn = http.start {|http| http.request(req) }
+        conn
+      end
+    end
+
+    def parse_response(resp)
+      JSON.parse resp.body
+    end
+
+    def set_params(params)
+      {}
+    end
+  end
+end

data/lib/ariadna/delegator.rb

@@ -0,0 +1,20 @@
+module Ariadna
+  class Delegator < BasicObject
+    
+    def initialize(target, owner)
+      @target       = target
+      @target.owner = owner
+    end
+
+    protected
+    
+    def method_missing(name, *args, &block)
+      target.send(name, *args, &block)
+    end
+
+    def target
+      @target ||= []
+    end
+
+  end
+end

data/lib/ariadna/error.rb

@@ -0,0 +1,11 @@
+module Ariadna
+  class Error < StandardError
+    attr_reader :errors, :code, :message
+  
+    def initialize(error_codes)
+      @errors  = ErrorCode.get_errors(error_codes["error"]["errors"])
+      @code    = error_codes["error"]["code"]
+      @message = error_codes["error"]["message"]
+    end
+  end
+end

data/lib/ariadna/error_code.rb

@@ -0,0 +1,22 @@
+module Ariadna
+  class ErrorCode
+    def initialize(item)
+      item.each do |k,v|
+        instance_variable_set("@#{k}", v)
+      end
+    end
+
+    def self.get_errors(errors)
+      create_attributes(errors.first)
+      errors.map do |item|
+        ErrorCode.new(item)
+      end
+    end
+
+    def self.create_attributes(item)
+      item.each do |k,v|
+        attr_reader k.to_sym
+      end
+    end
+  end
+end

data/lib/ariadna/profile.rb

@@ -0,0 +1,42 @@
+module Ariadna
+  class Profile
+
+    class << self; 
+      attr_accessor :owner 
+    end
+
+    attr_reader :id, :link, :name, :goals, :parent
+    
+    def initialize(item)
+      item.each do |k,v|
+        instance_variable_set("@#{k}", v)
+      end
+    end
+
+    def self.all
+      @profiles ||= create_profiles
+    end
+
+    def results
+      Delegator.new(Result, self)
+    end
+
+    private
+
+    def self.create_profiles
+      profiles = Ariadna.connexion.get_url(@owner.childLink["href"])
+      if (profiles["totalResults"].to_i > 0)
+        create_attributes(profiles["items"])
+        profiles["items"].map do |item|
+          Profile.new(item)
+        end
+      end
+    end
+
+    def self.create_attributes(items)
+      items.first.each do |k,v|
+        attr_reader k.to_sym
+      end
+    end
+  end
+end

data/lib/ariadna/result.rb

@@ -0,0 +1,167 @@
+module Ariadna
+  class Result
+
+    class << self
+      attr_accessor :owner
+      attr_accessor :url
+    end
+
+    URL = "https://www.googleapis.com/analytics/v3/data/ga"
+
+    #gel all results
+    def self.all
+      get_results
+    end
+
+    # metrics and dimensions
+
+    def self.select(params)
+      get_metrics_and_dimensions(params)
+      self
+    end
+
+    # main filter conditions 
+    def self.where(params)
+      extract_dates(params)
+      get_filters(params) unless params.empty?
+      self
+    end
+
+    # sort conditions for the query
+    def self.order(params)
+      conditions.merge!({"sort" => api_compatible_names(params)})
+      self
+    end
+
+    # number of results returned
+    def self.limit(results)
+      if ((results.to_i > 0) and (results.to_i < 1001))
+        conditions.merge!({"max-results" => results.to_i})
+      end
+      self
+    end
+
+    # number of row from which to start collecting results (used for pagination)
+    def self.offset(offset)
+      if (offset.to_i > 0) 
+        conditions.merge!({"start-index" => offset.to_i})
+      end
+      self
+    end
+
+    # lazy load query.  Only executed when actually needed
+    def self.each(&block)
+      get_results.each(&block)
+    end
+
+    private
+
+    def self.conditions
+      @conditions ||= {}
+    end
+
+    def self.accessor_name(header)
+      header["name"].sub('ga:', '')
+    end
+
+    # create attributes for each metric and dimension
+    def self.create_attributes(results)
+      summary_rows = Hash.new
+      summary_rows.merge!(results)
+      summary_rows.delete("columnHeaders")
+      summary_rows.delete("rows")
+      summary_rows.each do |row, value|
+        attr_reader row.to_sym
+      end
+      summary_rows
+    end
+
+    # create attributes for each metric and dimension
+    def self.create_metrics_and_dimensions(headers)
+      headers.each do |header|
+        attr_reader accessor_name(header).to_sym
+      end
+    end
+
+    # map the json results collection into result objects
+    # every metric and dimension is created as an attribute
+    # I.E. You can get result.visits or result.bounces
+    def self.get_results 
+      self.url = generate_url
+      results  = Ariadna.connexion.get_url(self.url)
+
+      return results unless results.is_a? Hash
+
+      if (results["totalResults"].to_i > 0)
+        #create an accessor for each summary attribute
+        summary_rows = create_attributes(results)
+        #create an accessor for each metric and dimension
+        create_metrics_and_dimensions(results["columnHeaders"])
+        results["rows"].map do |items|
+          res = Result.new
+          #assign values to summary fields
+          summary_rows.each do |name, value|
+            res.instance_variable_set("@#{name}", value)
+          end
+          #assign values to metrics and dimensions
+          items.each do |item|
+            res.instance_variable_set("@#{accessor_name(results["columnHeaders"][(items.index(item))])}", set_value_for_result(results["columnHeaders"][(items.index(item))], item))
+          end
+          res
+        end
+      end
+    end
+
+    def self.set_value_for_result(header, item)
+      case header["dataType"]
+      when "INTEGER"
+        return item.to_i
+      when "CURRENCY"
+        return item.to_d
+      when "FLOAT"
+        return item.to_f
+      when "TIME"
+        Time.at(item.to_d).gmtime.strftime('%R:%S')
+      else
+        return item.to_s
+      end
+    end
+
+    def self.generate_url
+      params = conditions.merge({"ids" => "ga:#{@owner.id}"})
+      "#{URL}?" + params.map{ |k,v| "#{k}=#{v}"}.join("&")
+    end
+
+    def self.get_filters(params)
+      filters = params.map do |k,v|
+          "#{api_compatible_names([k])}#{url_encoded_value(v)}"
+      end
+      conditions.merge!({"filters" => filters.join(",")})
+    end
+
+    def self.get_metrics_and_dimensions(params)
+      params.each do |k,v|
+        conditions.merge!({"#{k}" => api_compatible_names(v)})
+      end
+    end
+
+    def self.api_compatible_names(values)
+      values.collect {|e| "ga:#{e}"}.join(",")
+    end
+
+    def self.extract_dates(params)
+      start_date = params.delete(:start_date)
+      end_date  = params.delete(:end_date)
+      conditions.merge!({"start-date" => format_date(start_date)})
+      conditions.merge!({"end-date" => format_date(end_date)})
+    end
+
+    def self.format_date(date)
+      date.strftime("%Y-%m-%d")
+    end
+
+    def self.url_encoded_value(value)
+      URI.escape(value, "=@!><")
+    end
+  end
+end

data/lib/ariadna/version.rb

@@ -0,0 +1,3 @@
+module Ariadna
+  VERSION = "1.0.0"
+end