adapi 0.0.8 → 0.0.9

data/lib/adapi/api.rb

@@ -1,18 +1,29 @@
 # encoding: utf-8
 
+# Basic adapi class, parent of all service classes
+
 module Adapi
   class Api
     extend ActiveModel::Naming
     include ActiveModel::Validations
-    include ActiveModel::Serialization
     include ActiveModel::Conversion
-    # TODO include ActiveModel::Dirty
 
     LOGGER = Config.setup_logger
 
+    API_EXCEPTIONS = [
+      AdsCommon::Errors::ApiException, 
+      AdsCommon::Errors::HttpError, 
+      AdwordsApi::Errors::ApiException
+    ]
+
     attr_accessor :adwords, :service, :version, :params,
       :id, :status, :xsi_type
 
+    # Returns hash of attributes for a model instance
+    #
+    # This is an implementation of ActiveRecord::Base#attributes method.
+    # Children of API model customize this method for their own attributes.
+    #
     def attributes
       { 'status' => status, 'xsi_type' => xsi_type }
     end
@@ -48,24 +59,7 @@ module Adapi
       self.send("#{k}=", v)
     end
 
-    # return parameters in hash
-    # filtered for API calls by default: without :id and :status parameters
-    # PS: attributes method always returns all specified attributes
-    #
-    def data(filtered = true)
-      data_hash = self.serializable_hash.symbolize_keys
-      
-      if filtered
-        data_hash.delete(:id)
-        data_hash.delete(:status)
-      end
-      
-      data_hash
-    end
-
-    # alias to instance method: data
-    # 
-    alias :to_hash :data
+    alias :to_hash :attributes
 
     # detects whether the instance has been saved already
     #
@@ -74,6 +68,9 @@ module Adapi
     end
 
     def self.create(params = {})
+      # FIXME deep symbolize_keys, probably through ActiveSupport
+      params.symbolize_keys!
+
       api_instance = self.new(params)
       api_instance.create
       api_instance
@@ -84,6 +81,8 @@ module Adapi
     # class
     #
     def self.update(params = {})
+      params.symbolize_keys!
+
       # PS: updating campaign without finding it is much faster
       api_instance = self.new()
       api_instance.id = params.delete(:id)
@@ -109,15 +108,13 @@ module Adapi
       
       begin    
         response = @service.mutate(operation)
-    
-      rescue AdsCommon::Errors::HttpError => e
-        self.errors.add(:base, e.message)
 
-      # traps any exceptions raised by AdWords API
-      rescue AdwordsApi::Errors::ApiException => e
-        error_key = "[#{self.xsi_type.underscore}]"
-  
-        self.errors.add(error_key, e.message)
+      rescue *API_EXCEPTIONS => e
+        # TODO probably obsolete. keep or remove?
+        # error_key = self.xsi_type.to_s.underscore rescue :base
+        # self.errors.add(error_key, e.message)
+
+        self.errors.add(:base, e.message)
       end
       
       response

data/lib/adapi/campaign.rb

@@ -1,65 +1,99 @@
 # encoding: utf-8
 
+# Class for CampaignService
+#
+# https://developers.google.com/adwords/api/docs/reference/latest/CampaignService
+
 module Adapi
   class Campaign < Api
 
-    # http://code.google.com/apis/adwords/docs/reference/latest/CampaignService.Campaign.html
-    #
-    attr_accessor :name, :serving_status, :start_date, :end_date, :budget,
-      :bidding_strategy, :network_setting, :criteria, :ad_groups
+    NETWORK_SETTING_KEYS = [ :target_google_search, :target_search_network, 
+      :target_content_network, :target_content_contextual, :target_partner_search_network ]
+
+    ATTRIBUTES = [ :name, :status, :serving_status, :start_date, :end_date, :budget,
+      :bidding_strategy, :network_setting, :campaign_stats, :criteria, :ad_groups,
+      :ad_serving_optimization_status ]
+
+    attr_accessor *ATTRIBUTES
 
     def attributes
-      super.merge('name' => name, 'start_date' => start_date, 'end_date' => end_date,
-        'budget' => budget, 'bidding_strategy' => bidding_strategy,
-        'network_setting' => network_setting, 'criteria' => criteria,
-        'ad_groups' => ad_groups)
+      super.merge Hash[ ATTRIBUTES.map { |k| [k, self.send(k)] } ]
     end
 
+    alias to_hash attributes
+
     validates_presence_of :name, :status
     validates_inclusion_of :status, :in => %w{ ACTIVE DELETED PAUSED }
 
     def initialize(params = {})
+      params.symbolize_keys!
+
       params[:service_name] = :CampaignService
       
       @xsi_type = 'Campaign'
 
-      %w{ name status start_date end_date budget bidding_strategy
-      network_setting criteria ad_groups}.each do |param_name|
-        self.send "#{param_name}=", params[param_name.to_sym]
+      ATTRIBUTES.each do |param_name|
+        self.send("#{param_name}=", params[param_name])
       end
 
-      # convert bidding_strategy to GoogleApi
-      # can be either string (just xsi_type) or hash (xsi_type with params)
-      # TODO validations for xsi_type
-      # 
-      unless @bidding_strategy.is_a?(Hash)
-        @bidding_strategy = { :xsi_type => @bidding_strategy }
-      end
+      # HOTFIX backward compatibility with old field for criteria
+      @criteria ||= params[:targets] || {}
+
+      @ad_groups ||= []
 
-      if @bidding_strategy[:bid_ceiling] and not @bidding_strategy[:bid_ceiling].is_a?(Hash)
-        @bidding_strategy[:bid_ceiling] = {
-          :micro_amount => Api.to_micro_units(@bidding_strategy[:bid_ceiling])
-        }
+      super(params)
+    end
+
+    def start_date=(a_date)
+      @start_date = parse_date(a_date) if a_date.present?
+    end
+
+    def end_date=(a_date)
+      @end_date = parse_date(a_date) if a_date.present?
+    end
+
+    def parse_date(a_date)
+      case a_date
+        when DateTime, Date, Time then a_date
+        # FIXME distiguish between timestamp and YYYYMMDD string
+        else DateTime.parse(a_date).strftime('%Y%m%d') 
       end
+    end
 
-      # convert budget to GoogleApi
-      # TODO validations for budget
-      #
-      # budget can be integer (amount) or hash
-      @budget = { :amount => @budget } unless @budget.is_a?(Hash)
-      @budget[:period] ||= 'DAILY'
-      if @budget[:amount] and not @budget[:amount].is_a?(Hash)
-        @budget[:amount] = { :micro_amount => Api.to_micro_units(@budget[:amount]) }
+    # setter for converting bidding_strategy to google format
+    # can be either string (just xsi_type) or hash (xsi_type with params)
+    # TODO validations for xsi_type
+    # 
+    # TODO watch out when doing update. according to documentation:
+    # "to modify an existing campaign's bidding strategy, use 
+    # CampaignOperation.biddingTransition" 
+    #
+    def bidding_strategy=(params = {})
+      unless params.is_a?(Hash)
+        params = { xsi_type: params }
+      else
+        if params[:bid_ceiling] and not params[:bid_ceiling].is_a?(Hash)
+          params[:bid_ceiling] = {
+            micro_amount: Api.to_micro_units(params[:bid_ceiling])
+          }
+        end
       end
-      # PS: not sure if this should be a default. maybe we don't even need it
-      @budget[:delivery_method] ||= 'STANDARD'
 
-      # HOTFIX backward compatibility with old field for criteria
-      @criteria ||= params[:targets] || {}
+      @bidding_strategy = params
+    end
 
-      @ad_groups ||= []
+    # setter for converting budget to GoogleApi
+    # budget can be integer (amount) or hash
+    #
+    def budget=(params = {})
+      # if it's single value, it's a budget amount
+      params = { amount: params } unless params.is_a?(Hash)
 
-      super(params)
+      if params[:amount] and not params[:amount].is_a?(Hash)
+        params[:amount] = { micro_amount: Api.to_micro_units(params[:amount]) }
+      end
+
+      @budget = params.merge( period: 'DAILY', delivery_method: 'STANDARD' ) 
     end
 
     # create campaign with ad_groups and ads
@@ -109,29 +143,150 @@ module Adapi
         end
       end
 
-      return true
+      true
     end
 
-    # general method for changing campaign data
-    # TODO enable updating of all campaign parts at once, same as for Campaign#create method
+    # Sets campaign data en masse, including criteria and ad_groups with keywords and ads
+    #
+    # Warning: campaign data are not refreshed after update! We'd have to do it by get method
+    # and that would slow us down. If you want to see latest data, you have to fetch them again
+    # manually: Campaign#find or Campaign#find_complete
     #
-    # TODO implement class method
+    # TODO implement primarily as class method, instance will be just a redirect with campaign_id
     # 
     def update(params = {})
-      # HOTFIX can't use current instance, gotta create new one
-      response = Adapi::Campaign.new().mutate(
-        :operator => 'SET', 
-        :operand => params.merge(:id => @id)
-      )
+      # REFACTOR for the moment, we use separate campaign object just to prepare and execute 
+      # campaign update request. This is kinda ugly and should be eventually refactored (if
+      # only because of weird transfer of potential errors later when dealing with response). 
+      #
+      # campaign basic data workflow: 
+      # parse given params by loading them into Campaign.new and reading them back, parsed
+      # REFACTOR should be parsed by separate Campaign class method
+      #
+      campaign = Adapi::Campaign.new(params)
+      # HOTFIX remove :service_name param inserted byu initialize method
+      params.delete(:service_name)
+      # ...and load parsed params back into the hash
+      params.keys.each { |k| params[k] = campaign.send(k) }
+      params[:id] = @id
 
-      return false unless (response and response[:value])
+      @criteria = params.delete(:criteria)
+      params.delete(:targets)
+      @ad_groups = params.delete(:ad_groups) || []
+
+      @bidding_strategy = params.delete(:bidding_strategy)
 
-      # faster than self.find
-      params.each_pair { |k,v| self.send("#{k}=", v) }
+      operation = { operator: 'SET', operand: params }
+
+      # BiddingStrategy update has slightly different DSL from other params 
+      # https://developers.google.com/adwords/api/docs/reference/v201109_1/CampaignService.BiddingTransition
+      #
+      # See this post about BiddingTransition limitations:
+      # https://groups.google.com/forum/?fromgroups#!topic/adwords-api/tmRk1m7PbhU
+      # "ManualCPC can transition to anything and everything else can only transition to ManualCPC" 
+      if @bidding_strategy
+        operation[:bidding_transition] = { target_bidding_strategy: @bidding_strategy }
+      end
+ 
+      campaign.mutate(operation)
+
+      unless campaign.errors.empty?
+        self.store_errors(campaign) and return false
+      end
+
+      # update campaign criteria
+      if @criteria && @criteria.size > 0
+        new_criteria = Adapi::CampaignCriterion.new(
+          :campaign_id => @id,
+          :criteria => @criteria
+        )
+
+        new_criteria.update!
+        
+        unless new_criteria.errors.empty?
+          self.store_errors(new_criteria) and return false
+        end
+      end
+
+      result = self.update_ad_groups!(@ad_groups)
+
+      result
+    end
+
+    # helper method that updates ad_groups. called from Campaign#update method
+    #
+    def update_ad_groups!(ad_groups = [])
+      return true if ad_groups.nil? or ad_groups.empty?
+
+      # FIXME deep symbolize_keys
+      ad_groups.map! { |ag| ag.symbolize_keys } 
+
+      # check if every ad_group has either :id or :name parameter
+      ad_groups.each do |ag|
+        if ag[:id].blank? && ag[:name].blank?
+          self.errors.add("AdGroup", "required parameter (:id or :name) is missing")
+          return false
+        end
+      end
+
+      # get current ad_groups
+      original_ad_groups = AdGroup.find(:all, :campaign_id => @id)
+
+      ad_groups.each do |ad_group_data|
+        ad_group_data[:campaign_id] = @id
+
+        # try to find campaign ad_group by id or name 
+        k, v = ad_group_data.has_key?(:id) ? [:id, ad_group_data[:id]] : [:name, ad_group_data[:name]] 
+        ad_group = original_ad_groups.find { |ag| ag[k] == v } 
+
+        # update existing ad_group 
+        if ad_group.present?
+          ad_group.update(ad_group_data)
+
+          original_ad_groups.delete_if { |ag| ag[k] == v }
+
+        # create non-existent ad_group
+        # TODO report error if searching by :id, because such ad_group should exists?
+        else
+          ad_group_data.delete(:id)
+          ad_group = AdGroup.create(ad_group_data)
+        end
+
+        unless ad_group.errors.empty?
+          self.store_errors(ad_group, "AdGroup \"#{ad_group[:id] || ad_group[:name]}\"") and return false
+        end
+      end
+
+      # delete ad_groups which haven't been updated
+      original_ad_groups.each do |ag| 
+        unless ag.delete
+          self.errors.add("AdGroup #{ag[:id]}", "could not be deleted")
+          self.store_errors(ad_group, "AdGroup #{ag[:id]}")
+          return false
+        end
+      end
 
       true
     end
 
+    # Shortcut for pattern used in Campaign#update method 
+    # When partial update fails, store errors in main campaign instance 
+    #
+    def store_errors(failed_instance, error_prefix = nil)
+      raise "Campaign#store_errors: Invalid object instance" unless failed_instance.respond_to?(:errors)
+
+      error_prefix ||= failed_instance.respond_to?(:xsi_type) ? failed_instance.xsi_type : nil
+
+      failed_instance.errors.messages.each_pair do |k, v|
+          k = "#{error_prefix}::#{k}" if error_prefix and (k != :base)
+
+          Array(v).each do |x| 
+            self.errors.add(k, x)
+          end
+      end
+    end
+
+
     def activate; update(:status => 'ACTIVE'); end
     def pause; update(:status => 'PAUSED'); end
 
@@ -163,7 +318,6 @@ module Adapi
       Campaign.find(:first, :id => @id)
     end
 
-
     # if nothing else than single number or string at the input, assume it's an
     # id and we want to find campaign by id
     #
@@ -185,10 +339,20 @@ module Adapi
         end
       end.compact
 
-      # TODO display the rest of the data
-      # TODO get NetworkSetting - setting as in fields doesn't work
+      # TODO make configurable (but for the moment, return everything)
+      select_fields = %w{ Id Name Status ServingStatus 
+        StartDate EndDate AdServingOptimizationStatus } 
+      # retrieve CampaignStats fields
+      select_fields += %w{ Clicks Impressions Cost Ctr }
+      # retrieve Budget fields
+      select_fields += %w{ Amount Period DeliveryMethod } 
+      # retrieve BiddingStrategy fields
+       select_fields += %w{ BiddingStrategy BidCeiling EnhancedCpcEnabled }
+      # retrieve NetworkSetting fields
+      select_fields += NETWORK_SETTING_KEYS.map { |k| k.to_s.camelize } 
+
       selector = {
-        :fields => ['Id', 'Name', 'Status', 'BiddingStrategy'],
+        :fields => select_fields,
         :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
         :predicates => predicates
       }
@@ -224,23 +388,5 @@ module Adapi
       campaign
     end
 
-    # Converts campaign data to hash - of the same structure which is used when
-    # creating a campaign.
-    #
-    # PS: could be implemented more succintly, but let's leave it like this for
-    # now, code can change and this is more readable
-    #
-    def to_hash
-      {
-        :id => self[:id],
-        :name => self[:name],
-        :status => self[:status],
-        :budget => self[:budget],
-        :bidding_strategy => self[:bidding_strategy],
-        :criteria => self[:criteria],
-        :ad_groups => self[:ad_groups]
-      }
-    end
-
   end
 end

data/lib/adapi/campaign_criterion.rb

@@ -39,7 +39,7 @@ module Adapi
       super(params)
     end
 
-    def create
+    def create(operator = 'ADD')
       # step 1 - convert input hash to new array of criteria
       # example: :language => [ :en, :cs ] -> [ [:language, :en], [:language, :cs] ]
       criteria_array = []
@@ -124,7 +124,7 @@ module Adapi
       # step 2 - convert individual criteria to low-level google params
       operations = criteria_array.map do |criterion_type, criterion_settings|
         {
-          :operator => 'ADD',
+          :operator => operator,
           :operand => {
             :campaign_id => @campaign_id,
             :criterion => CampaignCriterion::create_criterion(criterion_type, criterion_settings)
@@ -136,7 +136,48 @@ module Adapi
 
       (response and response[:value]) ? true : false
     end
+
+    # custom update method, which delete all current criteria and adds new ones
+    #
+    def update!
+      result = self.delete_all!
+
+      # TODO return error if result == false
+
+      self.create
+    end
+
+    # REFACTOR
+    def destroy
+      self.create('REMOVE')
+    end
   
+    # Deletes all current campaign criteria
+    #
+    def delete_all!
+      # find all current criteria and extract operand params from them 
+      original_criteria = CampaignCriterion.find(:campaign_id => @campaign_id).map do |criterion|
+        criterion.select { |k,v| [ :xsi_type, :id ].include?(k) }
+      end
+
+      # HOTFIX temporarily remove platforms, adwords api throws error on no platforms
+      original_criteria.delete_if { |c| c[:xsi_type] == "Platform" }
+
+      operations = original_criteria.map do |criterion|
+        {
+          :operator => 'REMOVE',
+          :operand => {
+            :campaign_id => @campaign_id,
+            :criterion => criterion
+          }
+        }
+      end
+      
+      response = self.mutate(operations)
+
+      (response and response[:value]) ? true : false
+    end
+
     def self.find(params = {})
       params.symbolize_keys!
       
@@ -154,10 +195,8 @@ module Adapi
         end
       end.compact
 
-      # TODO: get more fields - tricky, because value files differ for most types
-      #
+      # TODO list all applicable fields in select fields
       selector = {
-        # HOTFIX added LocationName - and values for other criterion types mysteriously appeared as well!
         :fields => ['Id', 'CriteriaType', 'KeywordText', 'LocationName'],
         :ordering => [{:field => 'Id', :sort_order => 'ASCENDING'}],
         :predicates => predicates

data/lib/adapi/config.rb

@@ -1,9 +1,6 @@
 # encoding: utf-8
 
-# This class hold configuration data for AdWords API
-
-# TODO enable this way of using configuration
-# Adapi::Campaign.create(:data => campaign_data, :account => :my_account_alias)
+# This class holds configuration data for AdWords API
 
 module Adapi
   class Config

data/lib/adapi/constant_data/language.rb

@@ -1,5 +1,15 @@
 # encoding: utf-8
 
+# ConstantData::Language provides searching language id by its code. It is used
+# a a helper function for targeting.
+#
+# PS: Previously it has been possible to target by language code. This is not
+# supported by AdWords API anymore.
+
+# TODO refactor in tests and targeting code as well, self.find should return nil
+# if nothing is found
+# TODO maybe refactor through Array#assoc method
+
 module Adapi
   class ConstantData::Language < ConstantData
 
@@ -22,11 +32,10 @@ module Adapi
       super(params)
     end
 
-    # Returns AdWords API language id based for language code
+    # Finds Language instance by language code or language id (numeric argument)
     #
     def self.find(code)
       
-      # let's also allow searching by id
       if code.is_a?(Integer)
         Language.new(
           :id => code,

data/lib/adapi/keyword.rb

@@ -84,13 +84,72 @@ module Adapi
 
       response = self.mutate(operations)
 
-      return false unless (response and response[:value])
+      # check for PolicyViolationErrors, set exemptions and try again
+      # TODO for now, this is only done once. how about setting a number of retries?
+      unless self.errors[:PolicyViolationError].empty?
+        # FIXME this works, but add exemptions_requests only for related keyword if possible 
+        operations.each_with_index do |operation, i|
+          operations[i][:exemption_requests] = self.errors[:PolicyViolationError].map do |error_key|
+            { :key => error_key }
+          end
+        end
+
+        self.errors.clear
+
+        response = self.mutate(operations)
+      end
+
+      return false unless self.errors.empty?
       
       self.keywords = response[:value].map { |keyword| keyword[:criterion] }
 
       true
     end
 
+    # keywords mutate wrapper, deals with PolicyViolations for ads
+    #
+    # REFACTOR use just one mutate method in Api class
+    #
+    def mutate(operation)
+      operation = [operation] unless operation.is_a?(Array)
+      
+      # fix to save space during specifyng operations
+      operation = operation.map do |op|
+        op[:operand].delete(:status) if op[:operand][:status].nil?
+        op
+      end
+      
+      begin
+        
+        response = @service.mutate(operation)
+
+      rescue *API_EXCEPTIONS => e
+
+        # return PolicyViolations in specific format so they can be sent again
+        # see adwords-api gem example for details: handle_policy_violation_error.rb
+        e.errors.each do |error|
+          # error[:xsi_type] seems to be broken, so using also alternative key
+          # also could try: :"@xsi:type" (but api_error_type seems to be more robust)
+          if (error[:xsi_type] == 'PolicyViolationError') || (error[:api_error_type] == 'PolicyViolationError')
+            if error[:is_exemptable]
+              self.errors.add(:PolicyViolationError, error[:key])
+            end
+
+            # return also exemptable errors, operation may fail even with them
+            self.errors.add(:base, "violated %s policy: \"%s\" on \"%s\"" % [
+              error[:is_exemptable] ? 'exemptable' : 'non-exemptable', 
+              error[:key][:policy_name], 
+              error[:key][:violating_text]
+            ])
+          else
+            self.errors.add(:base, e.message)
+          end
+        end # of errors.each
+      end
+
+      response
+    end
+
     def self.find(amount = :all, params = {})
       params[:format] ||= :google # default, don't do anything with the data from google
       

data/lib/adapi/version.rb

@@ -1,12 +1,21 @@
 # encoding: utf-8
 
 module Adapi
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 
   # CHANGELOG:
   #
+  # 0.0.9
+  # added Campaign#update method - updates campaign, criteria and ad groups by a single method call
+  # fixed PolicyViolation exemptions for keywords and ads
+  # fixed and refactored error handling for most models
+  # refactored AdWords model attributes structure, simplify the code
+  # update find methods for most models to display all attributes
+  # updated gem dependencies (i.e. google-adwords-api to 0.6.2)
+  # refactor SOAP logging - get rid of monkeypatch
+  #
   # 0.0.8
-  # updated to AdWords API version v201109
+  # updated to AdWords API version v201109_1
   # updated gem dependencies
   # removed obsolete monkeypatches
   # improved SOAP logging - enable pretty logging and configurable log path