ppc_logic 0.8.0

data/lib/madmen/google/campaign.rb

@@ -0,0 +1,307 @@
+# Campaign represents a Google AdWords campaign object. You can create, destroy, find, and modify 
+# AdWords campaigns using the instance and class methods defined here. 
+#
+# Refer to Madmen::Google::Campaign for details.
+module Madmen #:nodoc:
+  module Google #:nodoc:
+    class Campaign
+      
+      attr_accessor :id
+      attr_accessor :name
+      attr_accessor :status
+      attr_accessor :daily_budget
+    
+      # Class Methods ==============================================================================
+
+      # Creates a new campaign.
+      #
+      # Usage:
+      #
+      #   c = Madmen::Google::Campaign.create(
+      #     :name => "My Campaign",
+      #     :status => 'PAUSED',
+      #     :budget => {
+      #       :period => 'DAILY',
+      #       :amount => { :microAmount => 100 * 1000000 },
+      #       :deliveryMethod => 'STANDARD'
+      #     }
+      #   )
+      #
+      # Returns:
+      #
+      #   A Campaign object.
+      #
+      def self.create(args)
+        operand = args
+        operand[:biddingStrategy] = Google.campaign_service.module::BudgetOptimizer.new
+        if response = Google.call_service(:campaign_service, :mutate, [{:operand => operand, :operator => 'ADD'}])
+          campaign = response.rval.value.first
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Campaign id %d was successfully added." % campaign.id)
+          return Campaign.new(
+            :name => campaign.name,
+            :id => campaign.id,
+            :status => campaign.status,
+            :daily_budget => campaign.budget.amount.microAmount / 1000000
+          )
+        else
+          return false
+        end
+      end
+      
+      # Retrieves an AdWords campaign from Google using the provided campaign id 
+      # and instantiates a Campaign object with its attributes.
+      #
+      # Usage:
+      #
+      #   Madmen::Google::Campaign.find(1)
+      #
+      # Returns:
+      #
+      #   A Campaign object.
+      #
+      def self.find(id)
+        raise ArgumentError, "Cannot find a campaign without an id!" unless id
+        selector = Google.campaign_service.module::CampaignSelector.new
+        selector.ids << id
+        if response = Google.call_service(:campaign_service, :get, selector)
+          return false unless response.rval.entries
+          campaign = response.rval.entries.first
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Campaign id %d was successfully retrieved." % campaign.id)
+          return Campaign.new(
+            :name => campaign.name,
+            :id => campaign.id,
+            :status => campaign.status,
+            :daily_budget => campaign.budget.amount.microAmount / 1000000
+          )
+        else
+          return false
+        end
+      end
+          
+      # Instance Methods ===========================================================================
+
+      # Instantiates a Campaign object, accepts a hash of optional parameters. 
+      # 
+      # Usage:
+      #
+      #   Madmen::Google::Campaign.new(:name => 'My Campaign')
+      #
+      # Returns:
+      # 
+      # A Campaign object.
+      #
+      def initialize(args)
+        @id = args[:id]
+        @name = args[:name]
+        @status = args[:status]
+        @daily_budget = args[:daily_budget]
+      end
+      
+      # Sets the status of the campaign to active.
+      def activate
+        set_status('active')
+      end
+      
+      # Returns associated ads (via its ad group)
+      def ads
+        return self.ad_group.ads if self.ad_group
+        return nil
+      end
+      
+      # Sets associated ads, via its ad group. Creates an ad group if necessary.
+      def ads=(ad_array)
+        create_ad_group unless self.ad_group
+        return self.ad_group.ads = ad_array
+      end
+      
+      # Returns the ad group associated with this campaign.
+      def ad_group
+        @ad_group ||= AdGroup.find_by_campaign_id(self.id)
+      end
+      
+      # Creates an ad group for this campaign.
+      def create_ad_group
+        return false if self.ad_group
+        return AdGroup.create( :campaign => self )
+      end
+      
+      # Sets the daily budget allocation for this campaign.
+      # Note that the amount should be in dollars; the budget amount is automatically converted
+      # to Google's MicroAmount currency value.
+      def daily_budget=(daily_budget)
+        operand = {:id => self.id}
+        operand["budget"] = {
+          :period => 'DAILY',
+          :amount => { :microAmount => daily_budget * 1000000 },
+          :deliveryMethod => 'STANDARD'
+        }
+        if response = Google.call_service(:campaign_service, :mutate, [{:operand => operand, :operator => 'SET'}])
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Campaign id %d daily budget set to #{daily_budget}." % self.id)
+          @daily_budget = daily_budget
+          return true
+        else
+          return false
+        end
+      end
+      
+      # Deletes the campaign from AdWords.
+      def delete
+        set_status('deleted')
+      end
+      
+      # Retrieves the keywords associated with this ad campaign.
+      def keywords
+        return [] unless self.ad_group
+        return self.ad_group.keywords
+      end
+      
+      # Sets the keywords associated with this ad campaign.
+      def keywords=(args)
+        create_ad_group unless self.ad_group
+        return self.ad_group.keywords = args
+      end
+      
+      # Sets the status of the campaign to paused.
+      def pause
+        set_status('paused')
+      end
+      
+      # Clear existing targeting information.
+      def reset_targeting
+        operand = Google.campaign_target_service.module::GeoTargetList.new
+        operand.campaignId = self.id
+        operand.targets = []
+        
+        if response = Google.call_service(:campaign_target_service, :mutate, [{:operand => operand, :operator => 'SET'}])
+          RAILS_DEFAULT_LOGGER.info "MADMEN: Cleared targeting for campaign"
+          return true
+        else
+          RAILS_DEFAULT_LOGGER.info "MADMEN: Unable to clear targeting for campaign"
+          return false
+        end
+      end
+      
+      # Returns the targeting type and details for the campaign.
+      def targeting
+        selector = Google.campaign_target_service.module::CampaignTargetSelector.new
+        selector << self.id
+        if response = Google.call_service(:campaign_target_service, :get, selector)
+          return nil unless response.rval && response.rval.entries.first
+          _targeting = response.rval.entries.select{|e| e.targets}.first.targets
+          case _targeting.first.target_Type
+            when "ProximityTarget"
+              return {
+                :kind => 'Proximity',
+                :targets => _targeting.inject([]){ |targets, t| targets << {:lat => t.geoPoint.longitudeInMicroDegrees / 1000000.0, :lng => t.geoPoint.latitudeInMicroDegrees / 1000000.0}; targets }
+              }
+            when "ProvinceTarget"
+              return {
+                :kind => 'States',
+                :targets => _targeting.inject([]){ |targets, t| targets << t.provinceCode.gsub(/US-/,'') }
+              }
+            when "CityTarget"
+              return {
+                :kind => 'Cities',
+                :targets => _targeting.inject([]){ |targets, t| targets << "#{t.cityName}, #{t.provinceCode.gsub(/US-/,'')}" }
+              }
+          end
+        else
+          return nil
+        end
+      end
+      
+      # Sets the geotarget for the campaign.
+      #
+      # Usage:
+      #
+      #   # Specific cities
+      #   adwords_campaign.targeting = {
+      #     :cities => [
+      #       {:city => 'Richmond', :state => 'VA'},
+      #       {:city => 'Petersburg', :state => 'VA'}
+      #     ]
+      #   }
+      #
+      #   # Specific states
+      #   adwords_campaign.targeting = {
+      #     :states => ["VA","DC"]
+      #   }
+      #
+      #   # Specific coordinates
+      #   adwords_campaign.targeting = {
+      #     :coords => [
+      #       {:lat => 38.0578, :lng => -97.9323}
+      #     ]
+      #   }
+      #
+      #   # Specific country
+      #   adwords_campaign.targeting = { :country => "US" }
+      #
+      def targeting=(args)
+        
+        self.reset_targeting
+        targets = []
+
+        if args[:cities]
+          args[:cities].each do |city|
+            target = Google.campaign_target_service.module::CityTarget.new
+            target.cityName = city[:city]
+            target.provinceCode = "US-#{city[:state]}"
+            target.countryCode = "US"
+            targets << target
+          end
+        elsif args[:states]
+          args[:states].each do |state|
+            target = Google.campaign_target_service.module::ProvinceTarget.new
+            target.provinceCode = "US-#{state}"
+            targets << target
+          end
+        elsif args[:coords]
+          args[:coords].each do |coord|
+            target = Google.campaign_target_service.module::ProximityTarget.new
+            geo_point = Google.campaign_target_service.module::GeoPoint.new
+            geo_point.longitudeInMicroDegrees = (coord[:lng] * 1000000).to_i
+            geo_point.latitudeInMicroDegrees = (coord[:lat] * 1000000).to_i
+            target.geoPoint = geo_point
+            target.radiusDistanceUnits = 'MILES'
+            target.radiusInUnits = 100
+            targets << target
+          end
+        elsif args[:country] # nationwide
+          target = Google.campaign_target_service.module::CountryTarget.new
+          target.countryCode = args[:country]
+          targets << target
+        else
+          raise ArgumentError, "Madmen: Could not determine targeting type from #{args}"
+        end
+
+        operand = Google.campaign_target_service.module::GeoTargetList.new
+        operand.campaignId = self.id
+        operand.targets = targets
+        
+        if response = Google.call_service(:campaign_target_service, :mutate, [{:operand => operand, :operator => 'SET'}])
+          RAILS_DEFAULT_LOGGER.info "Madmen: Set geotargeting to #{args.keys.first.to_s}"
+          return true
+        else
+          return false
+        end
+      end
+      
+      private
+      
+      def set_status(status)
+        self.status = status
+        operand = {:id => self.id}
+        operand["status"] = status.upcase
+        if response = Google.call_service(:campaign_service, :mutate, [{:operand => operand, :operator => 'SET'}])
+          campaign = response.rval.value.first
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Campaign id %d was successfully set to #{status}." % campaign.id)
+          return true
+        else
+          return false
+        end
+      end
+    
+    end
+  end
+end

data/lib/madmen/google/keyword.rb

@@ -0,0 +1,123 @@
+module Madmen #:nodoc:
+  module Google #:nodoc:
+    class Keyword
+    
+      attr_accessor :id
+      attr_accessor :match_type
+      attr_accessor :text
+      attr_accessor :ad_group_id
+      
+      # Class Methods ==============================================================================
+      
+      # Creates a new keyword in the specified ad group.
+      #
+      # Usage:
+      #
+      #   Keyword.create(:ad_group_id => 1, :text => 'foo', :match_type => 'broad')
+      #
+      def self.create(args)
+        return false if Keyword.exists?(args)
+        operation = Google.ad_group_criterion_service.module::AdGroupCriterionOperation.new
+        operand = Google.ad_group_criterion_service.module::BiddableAdGroupCriterion.new
+        operand.adGroupId = args[:ad_group_id]
+        keyword = Google.ad_group_criterion_service.module::Keyword.new
+        keyword.matchType = args[:match_type].upcase
+        keyword.text = args[:text]
+        operand.criterion = keyword
+        operation.operand = operand
+        operation.operator = 'ADD'
+        operation.exemptionRequests = []
+
+        if response = Google.call_service(:ad_group_criterion_service, :mutate, [operation])
+          criterion = response.rval.value.first.criterion
+          keyword = Keyword.new(:id => criterion.id, :text => criterion.text, :match_type => criterion.matchType)
+          RAILS_DEFAULT_LOGGER.info 'MADMEN: Keyword id %d was successfully created.' % keyword.id
+          return keyword
+        else
+          return false
+        end
+      end
+      
+      # Checks to see if a given keyword already exists for the specified ad group.
+      #
+      # Usage:
+      #
+      #   Keyword.exists?(:ad_group_id => 1, :text => 'foo', :match_type =>'exact')
+      #
+      def self.exists?(args)
+        _keywords = Keyword.find_by_ad_group_id(args[:ad_group_id])
+        return false if _keywords.blank?
+        !! _keywords.detect{|keyword| keyword.text == args[:text] && keyword.match_type.upcase == args[:match_type].upcase}
+      end
+      
+      # Retrieves a set of keywords from the specified ad group.
+      #
+      # Usage:
+      #
+      #   Keyword.find_by_ad_group_id(1)
+      #
+      # Returns:
+      #
+      # An array of Keyword objects, or an empty array if no keywords were found.
+      #
+      def self.find_by_ad_group_id(id)
+        raise ArgumentError, 'Cannot find keywords without an ad group ID!' unless id
+        selector = Google.ad_group_criterion_service.module::AdGroupCriterionSelector.new
+        filter = Google.ad_group_criterion_service.module::AdGroupCriterionIdFilter.new
+        filter.adGroupId = id
+        selector.idFilters = filter
+        
+        if response = Google.call_service(:ad_group_criterion_service, :get, selector)
+          entries = response.rval.entries
+          RAILS_DEFAULT_LOGGER.info("MADMEN: Keywords from ad group id %d were successfully retrieved." % id)
+          keywords = []
+          keywords = entries.map{|entry| entry.criterion}.inject([]){|keywords, keyword| keywords << Keyword.new(:text => keyword.text, :match_type => keyword.matchType, :id => keyword.id, :ad_group_id => id); keywords } if entries
+          return keywords
+        else
+          return []
+        end
+      end
+
+      # Instance Methods ===========================================================================
+
+      # Create a new Keyword object. Accepts a hash of optional arguments:
+      #
+      #   id
+      #   text
+      #   match_type
+      #   ad_group_id
+      #
+      # Match type must be one of: broad, exact, or phrase
+      #
+      def initialize(args)
+        @id = args[:id]
+        @text = args[:text]
+        @match_type = args[:match_type].downcase if args[:match_type]
+        @ad_group_id = args[:ad_group_id]
+      end
+      
+      # Deletes a keyword from its ad group.
+      def delete
+        operation = Google.ad_group_criterion_service.module::AdGroupCriterionOperation.new
+        operand = Google.ad_group_criterion_service.module::AdGroupCriterion.new
+        keyword = Google.ad_group_criterion_service.module::Keyword.new
+        keyword.id = self.id
+        keyword.text = self.text
+        keyword.matchType = self.match_type.upcase
+        operand.adGroupId = self.ad_group_id
+        operand.criterion = keyword
+        operation.operand = operand
+        operation.operator = 'REMOVE'
+        
+        if response = Google.call_service(:ad_group_criterion_service, :mutate, [operation])
+          RAILS_DEFAULT_LOGGER.info 'MADMEN: Keyword id %d was successfully removed.' % self.id
+          return true
+        else
+          return false
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/ppc_logic.rb

@@ -0,0 +1,19 @@
+module PpcLogic
+
+  require 'mongoid'
+  require 'ppc_logic/engine' if defined?(Rails)
+  require 'ppc_logic/railtie' if defined?(Rails)
+
+  mattr_accessor :adwords_developer_token
+  mattr_accessor :adwords_application_token
+  mattr_accessor :adwords_email
+  mattr_accessor :adwords_client_email
+  mattr_accessor :adwords_password
+  mattr_accessor :adwords_user_agent
+  mattr_accessor :adwords_environment
+
+  def self.setup
+    yield self
+  end
+
+end