ppc_logic 0.8.0

data/features/support/env.rb

@@ -0,0 +1,33 @@
+# IMPORTANT: This file is generated by cucumber-rails - edit at your own peril.
+# It is recommended to regenerate this file in the future when you upgrade to a
+# newer version of cucumber-rails. Consider adding your own code to a new file
+# instead of editing this one. Cucumber will automatically load all features/**/*.rb
+# files.
+
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
+
+require 'cucumber/formatter/unicode' # Remove this line if you don't want Cucumber Unicode support
+require 'cucumber/rails/rspec'
+require 'cucumber/rails/world'
+require 'cucumber/web/tableish'
+
+require 'capybara/rails'
+require 'capybara/cucumber'
+require 'capybara/session'
+# require 'cucumber/rails/capybara_javascript_emulation' # Lets you click links with onclick javascript handlers without using @culerity or @javascript
+# Capybara defaults to XPath selectors rather than Webrat's default of CSS3. In
+# order to ease the transition to Capybara we set the default here. If you'd
+# prefer to use XPath just remove this line and adjust any selectors in your
+# steps to use the XPath syntax.
+Capybara.default_selector = :css
+
+# How to clean your database when transactions are turned off. See
+# http://github.com/bmabey/database_cleaner for more info.
+if defined?(ActiveRecord::Base)
+  begin
+    require 'database_cleaner'
+    DatabaseCleaner.strategy = :truncation
+  rescue LoadError => ignore_if_database_cleaner_not_present
+  end
+end

data/features/support/hooks.rb

@@ -0,0 +1,4 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec/blueprints')
+require 'database_cleaner'
+require 'database_cleaner/cucumber'
+DatabaseCleaner.strategy = :truncation

data/features/support/paths.rb

@@ -0,0 +1,33 @@
+module NavigationHelpers
+  # Maps a name to a path. Used by the
+  #
+  #   When /^I go to (.+)$/ do |page_name|
+  #
+  # step definition in web_steps.rb
+  #
+  def path_to(page_name)
+    case page_name
+
+    when /the home\s?page/
+      '/'
+
+    # Add more mappings here.
+    # Here is an example that pulls values out of the Regexp:
+    #
+    #   when /^(.*)'s profile page$/i
+    #     user_profile_path(User.find_by_login($1))
+
+    else
+      begin
+        page_name =~ /the (.*) page/
+        path_components = $1.split(/\s+/)
+        self.send(path_components.push('path').join('_').to_sym)
+      rescue Object => e
+        raise "Can't find mapping from \"#{page_name}\" to a path.\n" +
+          "Now, go and add a mapping in #{__FILE__}"
+      end
+    end
+  end
+end
+
+World(NavigationHelpers)

data/init.rb

@@ -0,0 +1 @@
+require 'ppc_logic'

data/lib/madmen.rb

@@ -0,0 +1,9 @@
+# Madmen provides an interface to Google AdWords, Bing adCenter, and Yahoo! Sponsored links for
+# the creation and management of SEM campaigns.
+module Madmen
+
+  require 'soap/wsdlDriver'
+  require 'soap/header/simplehandler'
+  require 'madmen/google'
+
+end

data/lib/madmen/google.rb

@@ -0,0 +1,97 @@
+module Madmen
+
+  # Wraps the Google AdWords API wrapper (!) through friendly custom classes representing the
+  # appropriate AdWords business objects.
+  module Google
+
+    require 'madmen/google/ad_group'
+    require 'madmen/google/ad'
+    require 'madmen/google/campaign'
+    require 'madmen/google/keyword'
+
+    # Credentials ==================================================================================
+
+    def self.credentials
+      {
+        'developerToken' => PpcLogic.adwords_developer_token,
+        'useragent' => "SEO Logic",
+        'password' => PpcLogic.adwords_password,
+        'email' => PpcLogic.adwords_email,
+        'clientEmail' => PpcLogic.adwords_client_email,
+        'applicationToken' => PpcLogic.adwords_application_token
+      }
+    end
+
+
+    # Services =====================================================================================
+
+    def self.ad_group_ad_service
+      @ad_group_ad_service ||= CLIENT.get_service('AdGroupAd', latest)
+    end
+
+    def self.ad_group_criterion_service
+      @ad_group_criterion_service ||= CLIENT.get_service('AdGroupCriterion', latest)
+    end
+
+    def self.ad_group_service
+      @ad_group_service ||= CLIENT.get_service('AdGroup', latest)
+    end
+
+    def self.campaign_service
+      @campaign_service ||= CLIENT.get_service('Campaign', latest)
+    end
+
+    def self.campaign_target_service
+      @campaign_target_service ||= CLIENT.get_service('CampaignTarget', latest)
+    end
+
+    def self.latest
+      @latest ||= AdWords::Service.latest_version
+    end
+
+    # Utility Methods ==============================================================================
+
+    def self.call_service(service, method, args)
+      begin
+        return self.send(service).send(method, args)
+      rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => error
+        Google.rescue_from_connnection_error(error)
+        return false
+      rescue AdWords::Error::UnknownAPICall => error
+        Google.rescue_from_unknown_api_call(error)
+        return false
+      rescue AdWords::Error::ApiError => error
+        Google.rescue_from_api_error(error)
+        return false
+      ensure
+        Google.report_api_usage
+      end
+    end
+
+    def self.report_api_usage
+      Rails.logger.info 'MADMEN: %d API units consumed total (%d in last call).' % [CLIENT.total_units, CLIENT.last_units]
+    end
+
+    def self.rescue_from_api_error(error)
+      Rails.logger.info 'MADMEN: SOAP Error: %s (code: %d)' % [error.soap_faultstring_ex, error.code_ex]
+      Rails.logger.info 'MADMEN: Trigger: %s' % error.trigger_ex unless error.trigger_ex.nil?
+      Rails.logger.info 'MADMEN: Source: %s' % error.backtrace.first
+    end
+
+    def self.rescue_from_connnection_error(error)
+      Rails.logger.info "MADMEN: #{error}"
+      Rails.logger.info 'MADMEN: Source: %s' % error.backtrace.first
+    end
+
+    def self.rescue_from_unknown_api_call(error)
+      Rails.logger.info "MADMEN: #{error}"
+      Rails.logger.info 'MADMEN: Source: %s' % error.backtrace.first
+    end
+
+    # Constants ====================================================================================
+
+    CLIENT = AdWords::API.new(AdWords::AdWordsCredentials.new(credentials))
+
+  end
+
+end

data/lib/madmen/google/ad.rb

@@ -0,0 +1,177 @@
+module Madmen #:nodoc:
+  module Google #:nodoc:
+    # Represents an AdWords ad. Ads belong to ad groups, but may be accessed via the campaign.
+    # 
+    # Note that ads may not be directly deleted; rather, assign ads to a campaign or ad group, and
+    # any existing ads that are left out will be automatically removed.
+    #
+    class Ad
+    
+      attr_accessor :id
+      attr_accessor :ad_group_id
+      attr_accessor :headline
+      attr_accessor :description_1
+      attr_accessor :description_2
+      attr_accessor :url
+      attr_accessor :display_url
+      
+      # Class Methods ==============================================================================
+      
+      # Usage:
+      #
+      #   Ad.create(
+      #     :ad_group_id  => 1,
+      #     :headline     => 'My Headline',
+      #     :description1 => 'Ad Line 1',
+      #     :description2 => 'Ad Line 2',
+      #     :url          => 'http://www.seologic.com/foo',
+      #     :displayUrl   => 'www.seologic.com',
+      #   )
+      #
+      # Returns:
+      #
+      # An Ad object on success; false on failure.
+      #
+      def self.create(args)
+        return false if Ad.exists?(args)
+        operand = Google.ad_group_ad_service.module::AdGroupAd.new
+        operand.adGroupId = args[:ad_group_id]
+        operand.ad = Google.ad_group_ad_service.module::TextAd.new
+        args.keys.each{|key| operand.ad.send("#{key}=", args[key]) unless key == :ad_group_id}
+        operand.status = 'ENABLED'
+        operation = Google.ad_group_ad_service.module::AdGroupAdOperation.new
+        operation.operand = operand
+        operation.operator = 'ADD'
+        if response = Google.call_service(:ad_group_ad_service, :mutate, [operation])
+          ad = response.rval.value.first.ad
+          RAILS_DEFAULT_LOGGER.info 'MADMEN: Text ad id %d was successfully added.' % ad.id
+          return Ad.new(
+            :id => ad.id,
+            :ad_group_id => args[:ad_group_id],
+            :headline => ad.headline,
+            :description_1 => ad.description1,
+            :description_2 => ad.description2,
+            :url => ad.url,
+            :display_url => ad.displayUrl
+          )
+        else
+          return false
+        end
+      end
+      
+      # Checks to see if a given ad already exists for the specified ad group.
+      #
+      # Usage:
+      #
+      #   Ad.exists?(
+      #     :ad_group_id => 1,
+      #     :ad => {
+      #       :headline       => 'My Headline',
+      #       :description_1  => 'Ad Line 1',
+      #       :description_2  => 'Ad Line 2',
+      #       :url            => 'http://www.seologic.com/foo',
+      #       :display_url    => 'www.seologic.com'
+      #     }
+      #   )
+      #
+      def self.exists?(args)
+        _ads = Ad.find_by_ad_group_id(args[:ad_group_id])
+        !! _ads.detect{|ad| ad.send(:to_hash) == args[:ad]}
+      end
+      
+      # Retrieves a set of ads based on their associated ad group id.
+      #
+      # Usage:
+      #
+      #   Ad.find_by_ad_group_id(1)
+      #
+      # Returns:
+      #
+      # An array of Ad objects, or an empty array if no ads were found.
+      #
+      def self.find_by_ad_group_id(id)
+        selector = Google.ad_group_ad_service.module::AdGroupAdSelector.new
+        selector.adGroupIds << id
+        if response = Google.call_service(:ad_group_ad_service, :get, selector)
+          entries = response.rval.entries
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Ads from ad group id %d were successfully retrieved." % id)
+          @ads = []
+          if entries
+            entries.map{|entry| entry.ad}.each do |ad|
+              @ads << Ad.new(
+                :headline => ad.headline,
+                :display_url => ad.displayUrl,
+                :url => ad.url,
+                :description_1 => ad.description1,
+                :description_2 => ad.description2,
+                :id => ad.id,
+                :ad_group_id => id
+              )
+            end
+          end
+          return @ads
+        else
+          return []
+        end
+      end
+
+      # Instance Methods ===========================================================================
+
+      # Create a new Ad object. Accepts a hash of optional arguments.
+      #
+      # Usage:
+      #
+      #   Madmen::Google::Ad.new(
+      #     :ad_group_id    => 1, 
+      #     :headline       => 'My Headline',
+      #     :description_1  => 'Ad Line 1',
+      #     :description_2  => 'Ad Line 2',
+      #     :url            => 'http://www.seologic.com/foo',
+      #     :display_url    => 'www.seologic.com'
+      #   )
+      #
+      # Returns:
+      #
+      # An Ad object.
+      #
+      def initialize(args)
+        @id = args[:id]
+        @headline = args[:headline]
+        @description_1 = args[:description_1]
+        @description_2 = args[:description_2]
+        @url = args[:url]
+        @display_url = args[:display_url]
+        @ad_group_id = args[:ad_group_id]
+      end
+      
+      private
+      
+      def delete
+        operation = Google.ad_group_ad_service.module::AdGroupAdOperation.new
+        operand = Google.ad_group_ad_service.module::AdGroupAd.new
+        ad = Google.ad_group_ad_service.module::Ad.new
+        ad.id = self.id
+        operand.ad = ad
+        operand.adGroupId = self.ad_group_id
+        operation.operand = operand
+        operation.operator = 'REMOVE'
+        if response = Google.call_service(:ad_group_ad_service, :mutate, [operation])
+          RAILS_DEFAULT_LOGGER.info 'MADMEN: Ad id %d was successfully removed.' % self.id
+          return true
+        else
+          return false
+        end
+      end
+      
+      def to_hash
+        _keys = []
+        self.instance_variables.each do |attr|
+          _keys << attr.gsub('@','').to_sym unless attr == "@id" || attr == "@ad_group_id"
+        end
+        _keys.inject({}){|values, key| values[key] = self.send(key); values}
+      end
+      
+    end
+    
+  end
+end

data/lib/madmen/google/ad_group.rb

@@ -0,0 +1,209 @@
+module Madmen #:nodoc:
+  module Google #:nodoc:
+    # An AdGroup represents a Google AdWords ad group object.
+    #
+    # Refer to Madmen::Google::AdGroup for details.
+    #
+    class AdGroup
+    
+      attr_accessor :id
+      attr_accessor :details # A dump of the associated adwords4r object
+      attr_accessor :name
+      attr_accessor :status
+      attr_accessor :ad_ids
+      attr_accessor :campaign_id
+      
+      # Class Methods ==============================================================================
+
+      # Creates a new AdGroup in Google AdWords.
+      #
+      # Usage:
+      #
+      #   Madmen::Google::AdGroup.create(
+      #     :campaign => my_adwords_campaign_object
+      #   )
+      #
+      # Returns:
+      # 
+      # An AdGroup object on success, false on failure.
+      #
+      def self.create(args)
+        _campaign = args[:campaign]
+        operation = {
+          :operand => {
+            :name => "#{_campaign.name} Ad Group #{Time.zone.now.to_i}",
+            :status => 'ENABLED',
+            :campaignId =>  _campaign.id
+          },
+          :operator => 'ADD'
+        }
+        if response = Google.call_service(:ad_group_service, :mutate, [operation])
+          ad_group = response.rval.value.first
+          RAILS_DEFAULT_LOGGER.info 'MADMEN: Ad group id %d was successfully added.' % ad_group.id
+          return AdGroup.new(
+            :name => ad_group.name,
+            :id => ad_group.id,
+            :status => ad_group.status,
+            :details => ad_group
+          )
+        else
+          return false
+        end
+      end
+      
+      # Finds the ad group associated with a campaign through the campaign id.
+      #
+      # Usage:
+      #
+      #   Madmen::Google::AdGroup.find_by_campaign_id(1)
+      #
+      # Returns:
+      #
+      # An AdGroup object on success, nil on failure.
+      #
+      def self.find_by_campaign_id(id)
+        raise ArgumentError, "Cannot find a campaign without an id!" unless id
+        selector = Google.ad_group_service.module::AdGroupSelector.new
+        selector.campaignId = id
+        if response = Google.call_service(:ad_group_service, :get, selector)
+          return nil unless response.rval && ! response.rval.entries.blank?
+          ad_group = response.rval.entries.first
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Ad group id %d was successfully retrieved." % ad_group.id)
+          return AdGroup.new(
+            :name => ad_group.name,
+            :id => ad_group.id,
+            :status => ad_group.status,
+            :details => ad_group
+          )
+        else
+          return nil
+        end
+      end
+
+      # Instance Methods ===========================================================================
+
+      # Creates an instance of the AdGroup class.
+      #
+      # Usage:
+      #
+      #   Madmen::Google::AdGroup.new(:name => 'My AdGroup', :status => 'enabled')
+      #
+      # Returns:
+      #
+      # An AdGroup object.
+      #
+      def initialize(args)
+        @id = args[:id]
+        @details = args[:details]
+        @name = args[:name]
+        @status = args[:status]
+        @campaign_id = args[:campaign_id]
+      end
+      
+      # Returns an array of ads associated with this ad group.
+      def ads
+        @ads ||= Google::Ad.find_by_ad_group_id(self.id)
+      end
+      
+      # Creates ads associated with this ad group, automatically skipping existing ads 
+      # in the arguments and deleting any existing ads that are not specified in the 
+      # arguments.
+      #
+      # Usage:
+      #
+      #   my_ad_group.ads = (
+      #     { 
+      #       :headline       => 'My Headline',
+      #       :description_1  => 'Desc 1',
+      #       :description_2  => 'Desc 2',
+      #       :url            => 'http://www.seologic.com/foo',
+      #       :display_url    => 'www.seologic.com'
+      #     },
+      #     { 
+      #       :headline       => 'My Headline 2',
+      #       :description_1  => 'Desc 1',
+      #       :description_2  => 'Desc 2',
+      #       :url            => 'http://www.seologic.com/foo',
+      #       :display_url    => 'www.seologic.com'
+      #     }
+      #   )
+      #
+      # Returns:
+      #
+      # An array of Ad objects.
+      #
+      def ads=(ads)
+        # Delete existing keywords not in the arg list
+        self.ads.each do |ad|
+          ad.send(:delete) unless ads.include?({:headline => ad.headline, :description_1 => ad.description_1, :description_2 => ad.description_2, :url => ad.url, :display_url => ad.display_url})
+        end
+      
+        ads.each{ |ad| Ad.create(:ad => ad, :ad_group_id => self.id) }
+        @ads = nil
+        return self.ads
+      end
+      
+      # Sets the status of this ad group to 'enabled'
+      def enable
+        set_status('enabled')
+      end
+      
+      # Deletes this ad group.
+      def delete
+        set_status('deleted')
+      end
+      
+      # Returns an array of keywords associated with this ad group.
+      def keywords
+        @keywords ||= Google::Keyword.find_by_ad_group_id(self.id)
+      end
+      
+      # Sets keywords associated with this ad group.
+      #
+      # Note that existing keywords in the arguments list will be ignored,
+      # while existing keywords that are not present in the arguments will be deleted.
+      #
+      # Usage:
+      #
+      #   ad_group.keywords = [
+      #     {:text => 'foo', :match_type => 'exact'},
+      #     {:text => 'bar', :match_type => 'exact'}
+      #   ]
+      #
+      # Returns:
+      #
+      # An array of Keyword objects.
+      #
+      def keywords=(keywords_array)
+        # Delete existing keywords not in the arg list
+        self.keywords.each do |keyword|
+          keyword.delete unless keywords_array.include?({:text => keyword.text, :match_type => keyword.match_type})
+        end
+        # Create keywords
+        keywords_array.each{ |keyword| Keyword.create(:text => keyword[:text], :match_type => keyword[:match_type], :ad_group_id => self.id) }
+        @keywords = nil
+        return self.keywords
+      end
+      
+      # Sets the status of this ad group to 'paused'
+      def pause
+        set_status('paused')
+      end
+      
+      private
+
+      def set_status(status)
+        operation = { :operand => { :id => self.id, :status => status.upcase }, :operator => 'SET' }
+        if response = Google.call_service(:ad_group_service, :mutate, [operation])
+          RAILS_DEFAULT_LOGGER.info "MADMEN: Ad group id %d was set to status #{status.upcase}." % self.id
+          self.status = status
+          return true
+        else
+          return false
+        end
+      end
+      
+    end
+    
+  end
+end