adapi 0.0.9 → 0.1.0

data/lib/adapi/ad_group_criterion.rb

@@ -6,10 +6,13 @@ module Adapi
   #
   class AdGroupCriterion < Api
 
-    attr_accessor :ad_group_id, :criterion_use
+    ATTRIBUTES = [ :ad_group_id, :criterion_use ]
 
+    attr_accessor *ATTRIBUTES 
+
+    # FIXME why we don't use :criterion_use parameter here?
     def attributes
-      super.merge('ad_group_id' => ad_group_id)
+      super.merge( ad_group_id: ad_group_id )
     end
 
     def initialize(params = {})
@@ -17,8 +20,8 @@ module Adapi
 
       @xsi_type = 'AdGroupCriterion'
 
-      %w{ ad_group_id criterion_use }.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
 
       super(params)

data/lib/adapi/ad_param.rb

@@ -2,22 +2,22 @@
 
 module Adapi
   class AdParam < Api
-    attr_accessor :ad_group_id, :criterion_id, :insertion_text, :param_index
+
+    ATTRIBUTES = [ :ad_group_id, :criterion_id, :insertion_text, :param_index ]
+
+    attr_accessor *ATTRIBUTES 
 
     validates_presence_of :ad_group_id, :criterion_id
 
     def attributes
-      super.merge(
-        'ad_group_id' => ad_group_id, 'criterion_id' => criterion_id,
-        'insertion_text' => insertion_text, 'param_index' => param_index
-      )
+      super.merge Hash[ ATTRIBUTES.map { |k| [k, self.send(k)] } ]
     end
 
     def initialize(params = {})
       params[:service_name] = :AdParamService
 
-      %w{ ad_group_id criterion_id insertion_text param_index }.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
 
       super(params)
@@ -26,7 +26,7 @@ module Adapi
     def create
       operation = {
         :operator => 'SET',
-        :operand => serializable_hash
+        :operand => self.attributes
       }
 
       begin
@@ -77,13 +77,5 @@ module Adapi
       response
     end
 
-    def serializable_hash
-      {
-        :ad_group_id    => ad_group_id,
-        :criterion_id   => criterion_id,
-        :param_index    => param_index,
-        :insertion_text => insertion_text
-      }
-    end
   end
 end

data/lib/adapi/api.rb

@@ -2,6 +2,10 @@
 
 # Basic adapi class, parent of all service classes
 
+# TODO create universal Api.attributes method (instead of having the same method in all subclasses)
+# TODO create universal Api.initialize method (some subclasses don't have to have their own initialize method)
+# TODO move common methods into separate Common class or module
+
 module Adapi
   class Api
     extend ActiveModel::Naming
@@ -16,6 +20,13 @@ module Adapi
       AdwordsApi::Errors::ApiException
     ]
 
+    # these exceptions help to control program flow
+    # during complex operations over campaigns and ad_groups
+    # 
+    class ApiError < Exception; end
+    class CampaignError < Exception; end
+    class AdGroupError < Exception; end
+
     attr_accessor :adwords, :service, :version, :params,
       :id, :status, :xsi_type
 
@@ -25,7 +36,7 @@ module Adapi
     # Children of API model customize this method for their own attributes.
     #
     def attributes
-      { 'status' => status, 'xsi_type' => xsi_type }
+      { status: status, xsi_type: xsi_type }
     end
 
     def initialize(params = {})
@@ -69,7 +80,7 @@ module Adapi
 
     def self.create(params = {})
       # FIXME deep symbolize_keys, probably through ActiveSupport
-      params.symbolize_keys!
+      params.symbolize_keys! if params.is_a?(Hash)
 
       api_instance = self.new(params)
       api_instance.create
@@ -92,7 +103,6 @@ module Adapi
       api_instance
     end
 
-
     # wrap AdWords add/update/destroy actions and deals with errors
     # PS: Keyword and Ad models have their own wrappers because of
     # PolicyViolations
@@ -106,20 +116,90 @@ module Adapi
         op
       end
       
-      begin    
+      begin
+
         response = @service.mutate(operation)
 
       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)
+        unless e.respond_to?(:errors)
+          self.errors.add(:base, e.message)
+          return false
+        end
+
+        e.errors.each do |error|
+          if (error[:xsi_type] == 'PolicyViolationError') || (error[:api_error_type] == 'PolicyViolationError')
+            # return exemptable PolicyViolations errors in custom format so we can request exemptions
+            # see adwords-api gem example for details: handle_policy_violation_error.rb
+            # so far, this applies only for keywords and ads
+            if error[:is_exemptable]
+              self.errors.add( :PolicyViolationError, error[:key].merge(
+                :operation_index => AdwordsApi::Utils.operation_index_for_error(error)
+              ) )
+            end
+
+            # besides PolicyViolations errors in custom format, return all errors also in regular format
+            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
+
+        false
       end
       
       response
     end
 
+    # Deals with campaign exceptions encountered during complex operations over AdWords API
+    # 
+    # Parameters:
+    # store_errors (default: true) - add errors to self.error collection
+    # raise_errors (default: false) - raises exception CampaignError (after optional saving errors)
+    #
+    def check_for_errors(adapi_instance, options = {})
+      options.merge!( store_errors: true, raise_errors: false )
+
+      # don't store errors in this case, because errors are already there
+      # and loop in store_errors method would cause application to hang
+      options[:store_errors] = false if (adapi_instance == self)
+
+      unless adapi_instance.errors.empty?
+        store_errors(adapi_instance, options[:prefix]) if options[:store_errors]
+
+        if options[:raise_errors]
+          exception_type = case adapi_instance.xsi_type
+            when "Campaign" then CampaignError
+            when "AdGroup" then AdGroupError
+            else ApiError
+          end
+
+          raise exception_type
+        end
+      end
+    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 "#{failed_instance.xsi_type}#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
+
     # convert number to micro units (unit * one million)
     #
     def self.to_micro_units(x)

data/lib/adapi/campaign.rb

@@ -12,7 +12,7 @@ module Adapi
 
     ATTRIBUTES = [ :name, :status, :serving_status, :start_date, :end_date, :budget,
       :bidding_strategy, :network_setting, :campaign_stats, :criteria, :ad_groups,
-      :ad_serving_optimization_status ]
+      :ad_serving_optimization_status, :settings ]
 
     attr_accessor *ATTRIBUTES
 
@@ -96,54 +96,72 @@ module Adapi
       @budget = params.merge( period: 'DAILY', delivery_method: 'STANDARD' ) 
     end
 
+    # setter for campaign settings (array of hashes)
+    #
+    def settings=(setting_options = [])
+      # for arrays, set in raw form 
+      @settings = if setting_options.is_a?(Array)
+        setting_options
+      # set optional shortcuts for settings
+      # :keyword_match_setting => { :opt_in => false } # =>
+      # { :xsi_type => 'KeywordMatchSetting', :opt_in => false }
+     elsif setting_options.is_a?(Hash)
+        setting_options.map do |key, values|
+          { :xsi_type => key.to_s.camelcase }.merge(values).symbolize_keys
+        end
+      end
+    end
+
     # create campaign with ad_groups and ads
     #
     def create
       return false unless self.valid?      
       
+      # create basic campaign attributes
       operand = Hash[
         [ :name, :status, :start_date, :end_date,
-          :budget, :bidding_strategy, :network_setting ].map do |k|
+          :budget, :bidding_strategy, :network_setting, :settings ].map do |k|
           [ k.to_sym, self.send(k) ] if self.send(k)
         end.compact
       ]
 
-      response = self.mutate(
-        :operator => 'ADD', 
-        :operand => operand
+      # set default values for settings (for create only - should we set it also for update?)
+      # PS: KeywordMatchSetting is required since 201206
+      operand[:settings] ||= []
+      unless operand[:settings].map { |s| s[:xsi_type] }.include?('KeywordMatchSetting')
+        operand[:settings] << { :xsi_type => 'KeywordMatchSetting', :opt_in => false }
+      end
+
+      response = self.mutate( 
+        operator: 'ADD', 
+        operand: operand
       )
-      
-      return false unless (response and response[:value])
-      
+
+      check_for_errors(self)
+
       self.id = response[:value].first[:id] rescue nil
       
-      # create criteria (former targets) if they are available
-      if criteria.size > 0
-        criterion = Adapi::CampaignCriterion.create(
-          :campaign_id => @id,
-          :criteria => criteria
+      if criteria && criteria.size > 0
+        new_criteria = Adapi::CampaignCriterion.create(
+          campaign_id: @id,
+          criteria: criteria
         )
-        
-        if (criterion.errors.size > 0)
-          self.errors.add("[campaign criterion]", criterion.errors.to_a)
-          self.rollback
-          return false 
-        end
+
+        check_for_errors(new_criteria)
       end
 
       ad_groups.each do |ad_group_data|
         ad_group = Adapi::AdGroup.create(
-          ad_group_data.merge(:campaign_id => @id)
+          ad_group_data.merge( campaign_id: @id )
         )
 
-        if (ad_group.errors.size > 0)
-          self.errors.add("[ad group] \"#{ad_group.name}\"", ad_group.errors.to_a)
-          self.rollback
-          return false 
-        end
+        check_for_errors(ad_group, :prefix => "AdGroup \"#{ad_group[:id] || ad_group[:name]}\"")
       end
 
-      true
+      self.errors.empty?
+
+    rescue CampaignError => e
+      false
     end
 
     # Sets campaign data en masse, including criteria and ad_groups with keywords and ads
@@ -176,7 +194,10 @@ module Adapi
 
       @bidding_strategy = params.delete(:bidding_strategy)
 
-      operation = { operator: 'SET', operand: params }
+      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
@@ -190,9 +211,7 @@ module Adapi
  
       campaign.mutate(operation)
 
-      unless campaign.errors.empty?
-        self.store_errors(campaign) and return false
-      end
+      check_for_errors(campaign)
 
       # update campaign criteria
       if @criteria && @criteria.size > 0
@@ -202,15 +221,16 @@ module Adapi
         )
 
         new_criteria.update!
-        
-        unless new_criteria.errors.empty?
-          self.store_errors(new_criteria) and return false
-        end
+
+        check_for_errors(new_criteria)        
       end
 
-      result = self.update_ad_groups!(@ad_groups)
+      self.update_ad_groups!(@ad_groups)
 
-      result
+      self.errors.empty?
+
+    rescue CampaignError => e
+      false
     end
 
     # helper method that updates ad_groups. called from Campaign#update method
@@ -235,7 +255,7 @@ module Adapi
       ad_groups.each do |ad_group_data|
         ad_group_data[:campaign_id] = @id
 
-        # try to find campaign ad_group by id or name 
+        # find 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 } 
 
@@ -245,84 +265,75 @@ module Adapi
 
           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?
+        # create new ad_group
+        # FIXME 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
+        check_for_errors(ad_group, :prefix => "AdGroup \"#{ad_group[:id] || ad_group[:name]}\"")
       end
 
       # delete ad_groups which haven't been updated
       original_ad_groups.each do |ag| 
         unless ag.delete
+          # FIXME storing error twice for the moment because neither
+          # of these errors says all the needed information
           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
+      self.errors.empty?
 
-      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
+    rescue CampaignError => e
+      false
     end
 
-
     def activate; update(:status => 'ACTIVE'); end
+
     def pause; update(:status => 'PAUSED'); end
 
-    # Deletes campaign - which means, sets its status to deleted (because
-    # AdWords campaigns are never really deleted.)
+    # Deletes campaign - which means simply setting its status to deleted
     #
     def delete; update(:status => 'DELETED'); end
 
     def rename(new_name); update(:name => new_name); end
 
-    # when Campaign#create fails, "delete" campaign
-
-    # Deletes campaign if it's not already deleted. For more information about
-    # "deleted" campaigns, see `delete` method
+    # Deletes campaign if not already deleted. This is usually done after 
+    # unsuccessfull complex operation (create/update complete campaign)
     #
-    def rollback
+    def rollback!
       if (@status == 'DELETED')
         self.errors.add(:base, 'Campaign is already deleted.')
         return false
       end
 
-      update(
+      self.errors.clear
+
+      self.update(
         :name => "#{@name}_DELETED_#{(Time.now.to_f * 1000).to_i}",
         :status => 'DELETED'
       )
     end
 
-    def find # == refresh
+    # Shortcut method, often used for refreshing campaign after create/update
+    # REFACTOR into :refresh method
+    #
+    def find
       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
+    # Searches for campaign/s according to given parameters
+    #
+    # Input parameters are dynamic.
+    # Special case: single number or string on input is considered to be id
+    # and we want to search for a single campaign by id
     #
     def self.find(amount = :all, params = {})
-      # find campaign by id - related syntactic sugar
+      # find single campaign by id
       if params.empty? and not amount.is_a?(Symbol)
         params[:id] = amount.to_i
         amount = :first
@@ -335,7 +346,7 @@ module Adapi
         if params[param_name]
           # convert to array
           value = Array.try_convert(params[param_name]) ? params_param_name : [params[param_name]]
-          {:field => param_name.to_s.camelcase, :operator => 'IN', :values => value }
+          { field: param_name.to_s.camelcase, operator: 'IN', values: value }
         end
       end.compact
 
@@ -347,13 +358,13 @@ module Adapi
       # retrieve Budget fields
       select_fields += %w{ Amount Period DeliveryMethod } 
       # retrieve BiddingStrategy fields
-       select_fields += %w{ BiddingStrategy BidCeiling EnhancedCpcEnabled }
+      select_fields += %w{ BiddingStrategy BidCeiling EnhancedCpcEnabled }
       # retrieve NetworkSetting fields
       select_fields += NETWORK_SETTING_KEYS.map { |k| k.to_s.camelize } 
 
       selector = {
         :fields => select_fields,
-        :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
+        :ordering => [ { field: 'Name', sort_order: 'ASCENDING' } ],
         :predicates => predicates
       }
 
@@ -383,7 +394,7 @@ module Adapi
       
       campaign[:criteria] = CampaignCriterion.find(:campaign_id => campaign.to_param)
 
-      campaign[:ad_groups] = AdGroup.find(:all, :campaign_id => campaign.to_param)
+      campaign[:ad_groups] = AdGroup.find(:all, :campaign_id => campaign.to_param).map { |ag| ag.to_hash }
 
       campaign
     end