adapi 0.0.8 → 0.0.9

data/examples/update_campaign_criteria.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+
+require 'adapi'
+
+require_relative 'add_campaign_criteria'
+
+=begin this is an obsolete way to do this
+Adapi::CampaignCriterion.new(
+  :campaign_id => $campaign[:id],
+  :criteria => {
+    :language => %w{ en cs},
+  }
+).destroy
+
+Adapi::CampaignCriterion.new(
+  :campaign_id => $campaign[:id],
+  :criteria => {
+    :language => %w{ sk },
+  }
+).create
+=end
+
+$new_criteria = Adapi::CampaignCriterion.new(
+  :campaign_id => $campaign[:id],
+  :criteria => {
+    :language => %w{ sk },
+  }
+)
+
+$result = $new_criteria.update!
+
+$campaign_criterion = Adapi::CampaignCriterion.find( :campaign_id => $campaign[:id] )
+pp $campaign_criterion

data/examples/update_complete_campaign.rb

@@ -0,0 +1,177 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# create campaign by single command, with campaing targets, with ad_groups
+# including keywords and ads
+
+$ad_group_names = [
+  "AdGroup 01 #%d" % (Time.new.to_f * 1000).to_i,
+  "AdGroup 02 #%d" % (Time.new.to_f * 1000).to_i
+]
+
+campaign_data = {
+  # basic data for campaign
+  :name => "Campaign #%d" % (Time.new.to_f * 1000).to_i,
+  :status => 'PAUSED',
+  :bidding_strategy => 'ManualCPC',
+  :budget => 50,
+  :network_setting => {
+    :target_google_search => true,
+    :target_search_network => true,
+    :target_content_network => false,
+    :target_content_contextual => false
+  },
+
+  :criteria => {
+    :language => [ :en, :cs ],
+    :geo => { :proximity => { :geo_point => '38.89859,-77.035971', :radius => '10 km' } }
+  },
+
+  :ad_groups => [
+    {
+      :name => $ad_group_names[0],
+      :status => 'ENABLED',
+
+      :keywords => [ 'neo', 'dem codez', '"top coder"', "[-code]" ],
+
+      :ads => [
+        {
+          :headline => "Code like Neo",
+          :description1 => 'Need mad coding skills?',
+          :description2 => 'Check out my new blog!',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        }
+      ]
+    },
+
+    {
+      :name => $ad_group_names[1],
+      :status => 'PAUSED',
+
+      :keywords => [ 'dem codez', 'trinity', 'morpheus', '"top coder"', "[-code]" ],
+
+      :ads => [
+        {
+          :headline => "Code like Trinity",
+          :description1 => 'The power of awesomeness?',
+          :description2 => 'Check out my new blog!',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        },
+
+        {
+          :headline => "Code like Morpheus",
+          :description1 => 'Unleash the power of Matrix',
+          :description2 => 'Check out my new blog',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        }        
+      ]
+    }    
+  ]
+
+}
+ 
+$campaign = Adapi::Campaign.create(campaign_data)
+p "Created campaign ID #{$campaign.id}"
+
+# PS: changes in ad_groups:
+# * delete first ad_group
+# * change second ad_group
+# * add new ad_group
+
+Adapi::Campaign.update(
+  :id => $campaign[:id],
+  :status => 'ACTIVE',
+  :name => "UPDATED #{$campaign[:name]}",
+  :bidding_strategy => { 
+    :xsi_type => 'BudgetOptimizer', 
+    :bid_ceiling => 20 
+  },
+  :budget => 75,
+
+  # deletes all criteria (except :platform) and create these new ones
+  :criteria => {
+    :language => [ :sk ],
+  },
+
+  :ad_groups => [
+    # no match here for $ad_group_names[0], so it's going to be deleted
+
+    # this ad_group will be created
+    {
+      :name => "UPDATED " + $ad_group_names[0],
+      :status => 'ENABLED',
+
+      :keywords => [ 'neo update', 'dem codezzz', '"top coder"' ],
+
+      :ads => [
+        {
+          :headline => "Update like Neo",
+          :description1 => 'Need mad coding skills?',
+          :description2 => 'Check out my new blog!',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        }
+      ]
+    },
+
+    # this ad_group is going to be updated
+    {
+      :name =>  $ad_group_names[1],
+      :status => 'ENABLED', # from PAUSED
+
+      :keywords => [ 'dem updatez', 'update trinity', 'update morpheus' ],
+
+      :ads => [
+        {
+          :headline => "Update like Trinity",
+          :description1 => 'The power of updates?',
+          :description2 => 'Check out my new blog!',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        },
+
+        {
+          :headline => "Update like Morpheus",
+          :description1 => 'Unleash the power of updates',
+          :description2 => 'Check out my new blog',
+          :url => 'http://www.demcodez.com',
+          :display_url => 'http://www.demcodez.com'
+        }        
+      ]
+    }    
+  ]
+)
+
+unless $campaign.errors.empty?
+
+  puts "ERROR WHEN UPDATING AD GROUPS:"
+  puts $campaign.errors.full_messages.join("\n")
+
+else
+
+  # reload campaign
+  $campaign = Adapi::Campaign.find_complete($campaign.id)
+
+  $campaign_attributes = $campaign.attributes
+  $criteria = $campaign_attributes.delete(:criteria)
+  $ad_groups = $campaign_attributes.delete(:ad_groups)
+
+  puts "\nCAMPAIGN UPDATED\n"
+
+  puts "\nCAMPAIGN DATA:"
+  pp $campaign_attributes
+
+  puts "\nCAMPAIGN CRITERIA:"
+  pp $criteria
+
+  puts "\nAD GROUPS (#{$ad_groups.size}):"
+  $ad_groups.each_with_index do |ad_group, i| 
+    puts "\nAD GROUP #{i + 1}:\n"
+    pp ad_group.attributes
+  end
+
+end

data/examples/update_text_ad.rb

@@ -0,0 +1,18 @@
+
+require 'adapi'
+
+require_relative 'add_text_ad'
+
+$new_ad = $ad.update(
+  :status => 'ACTIVE',
+  :headline => "Code like Trinity",
+  :description1 => 'Need mad update skills?',
+  :description2 => 'Check out my updates!',
+  :url => 'http://www.demupdatez.com',
+  :display_url => 'http://www.demupdatez.com'
+)
+
+$new_ad = Adapi::Ad::TextAd.find(:first, :ad_group_id => $new_ad.ad_group_id, :id => $new_ad.id )
+
+puts "\nUPDATED (AND RELOADED) AD:"
+pp $new_ad.attributes

data/lib/adapi/ad/text_ad.rb

@@ -7,19 +7,23 @@ module Adapi
   #
   class Ad::TextAd < Ad
 
-    attr_accessor :headline, :description1, :description2
+    ATTRIBUTES = [ :headline, :description1, :description2 ]
+
+    attr_accessor *ATTRIBUTES
 
     def attributes
-      super.merge('headline' => headline, 'description1' => description1, 'description2' => description2)
+      super.merge Hash[ ATTRIBUTES.map { |k| [k, self.send(k)] } ]
     end
 
+    alias to_hash attributes
+
     def initialize(params = {})
       params[:service_name] = :AdGroupAdService
 
       @xsi_type = 'TextAd'
 
-      %w{ headline description1 description2 }.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)
@@ -30,57 +34,58 @@ module Adapi
     end
  
     def create
+      operand = self.attributes.delete_if do |k|
+        [ :campaign_id, :ad_group_id, :id, :status ].include?(k.to_sym)
+      end.symbolize_keys
+
       operation = {
         :operator => 'ADD',
         :operand => {
           :ad_group_id => @ad_group_id,
           :status => @status,
-          :ad => self.data
+          :ad => operand
         }
       }
 
       response = self.mutate(operation)
- 
-      # check for PolicyViolationError(s)
-      # PS: check google-adwords-api/examples/handle_policy_violation_error.rb
-      if (self.errors['PolicyViolationError'].size > 0)
-        # set exemptions and try again
-        operation[:exemption_requests] = errors['PolicyViolationError'].map do |error|
-          { :key => error }
+
+      # 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?
+        operation[:exemption_requests] = self.errors[:PolicyViolationError].map do |error_key|
+          { :key => error_key }
         end
 
         self.errors.clear
 
-        response = self.mutate(operation)  
+        response = self.mutate(operation)
       end
 
-      return false unless (response and response[:value])
-  
+      return false unless self.errors.empty?
+          
+      # set ad id
       self.id = response[:value].first[:ad][:id] rescue nil
   
       true
     end
 
-    # params - specify hash of params and values to update
-    # PS: I think it's possible to edit only status, but not headline,
-    # descriptions... instead you should delete existing ad and create a new one
+    # except for status, we cannot edit ad fields
+    # gotta delete an ad and create a new one instead
+    # this means that this method returns new ad id! 
+    # 
+    # REFACTOR this method shpould be removed (but that might break something,
+    # os let's keep it here for the moment)
     #
     def update(params = {})
-      # set params (:status param makes it a little complicated)
-      #
-      updated_params = (params || self.attributes).symbolize_keys
-      updated_status = updated_params.delete(:status)
-      
-      response = self.mutate(
-        :operator => 'SET', 
-        :operand => {
-          :ad_group_id => self.ad_group_id,
-          :ad => updated_params.merge(:id => self.id),
-          :status => updated_status
-        }
-      )
+      # set attributes for the "updated" ad
+      create_attributes = self.attributes.merge(params).symbolize_keys
+      create_attributes.delete(:id)
+
+      # delete current ad
+      return false unless self.destroy
 
-      (response and response[:value]) ? true : false
+      # create new add
+      TextAd.create(create_attributes)
     end
 
     def find # == refresh
@@ -101,13 +106,12 @@ module Adapi
       # supported condition parameters: ad_group_id and id
       predicates = [ :ad_group_id, :id ].map do |param_name|
         if params[param_name]
-          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 => Array( params[param_name] ) }
         end
       end.compact
 
       selector = {
-        :fields => ['Id', 'Headline'],
+        :fields => ['Id', 'AdGroupId', 'Headline' ],
         :ordering => [{:field => 'Id', :sort_order => 'ASCENDING'}],
         :predicates => predicates
       }
@@ -121,22 +125,8 @@ module Adapi
       end
 
       # TODO convert to TextAd instances
-      # PS: we already have ad_group_id parameter
       first_only ? response.first : response
     end
 
-    # Converts text ad data to hash - of the same structure which is used when
-    # creating a complete campaign.
-    #
-    def to_hash
-      {
-        :headline => self[:headline],
-        :description1 => self[:description1],
-        :description2 => self[:description2],
-        :url => self[:url],
-        :display_url => self[:display_url]
-      }
-    end
-
   end
 end

data/lib/adapi/ad.rb

@@ -6,7 +6,9 @@ module Adapi
   # wraps all types of ads: text ads, image ads...
   class Ad < Api
 
-    attr_accessor :ad_group_id, :url, :display_url, :approval_status,
+    # REFACTOR attributes
+
+    attr_accessor :id, :ad_group_id, :url, :display_url, :approval_status,
       :disapproval_reasons, :trademark_disapproved
 
     validates_presence_of :ad_group_id
@@ -14,7 +16,8 @@ module Adapi
     # PS: create won't work with id and ad_group_id
     # 'id' => id, 'ad_group_id' => ad_group_id, 
     def attributes
-      super.merge('url' => url, 'display_url' => display_url)
+      super.merge( 'id' => id, 'ad_group_id' => ad_group_id, 
+        'url' => url, 'display_url' => display_url )
     end
 
     def initialize(params = {})
@@ -33,15 +36,14 @@ module Adapi
       response = self.mutate(
         :operator => 'REMOVE',
         :operand => {
-          :ad_group_id => self.ad_group_id,
-          :ad => { :id => self.id, :xsi_type => 'Ad' }
+          :ad_group_id => @ad_group_id,
+          :ad => { :id => @id, :xsi_type => 'Ad' }
         }
       )
 
       (response and response[:value]) ? true : false
     end
 
-
     # ad-specific mutate wrapper, deals with PolicyViolations for ads
     #
     def mutate(operation)
@@ -53,25 +55,34 @@ module Adapi
         op
       end
       
-      begin    
+      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
-        # return PolicyViolations so they can be sent again
+      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|
-          if (error[:api_error_type] == 'PolicyViolationError') && error[:is_exemptable]
-            self.errors.add(error[:api_error_type], error[:key])
-          else 
-            # otherwise, just report the errors
-            self.errors.add( "[#{self.xsi_type.underscore}]", "#{error[:error_string]} @ #{error[:field_path]}")
+          # 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
+        end # of errors.each
       end
-      
+
       response
     end
 

data/lib/adapi/ad_group.rb

@@ -1,31 +1,49 @@
 # encoding: utf-8
 
+# This class handles operations with ad_groups
+#
+# https://developers.google.com/adwords/api/docs/reference/latest/AdGroupService
+#
 module Adapi
   class AdGroup < Api
   
-    attr_accessor :campaign_id, :name, :bids, :keywords, :ads
+    ATTRIBUTES = [ :id, :campaign_id, :name, :status, :bids, :keywords, :ads ]
+
+    attr_accessor *ATTRIBUTES 
 
     validates_presence_of :campaign_id, :name, :status
     validates_inclusion_of :status, :in => %w{ ENABLED PAUSED DELETED }
 
     def attributes
-      super.merge('campaign_id' => campaign_id, 'name' => name, 'bids' => bids)
+      super.merge Hash[ ATTRIBUTES.map { |k| [k, self.send(k)] } ]
     end
 
+    alias to_hash attributes
+
     def initialize(params = {})
       params[:service_name] = :AdGroupService
 
       @xsi_type = 'AdGroup'
 
-      %w{ campaign_id name status bids keywords ads }.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 bids to GoogleApi format
-      #
-      # can be either string (just xsi_type) or hash (xsi_type with params)
-      # although I'm not sure if just string makes sense in this case
-      #
+      @keywords ||= []
+
+      @ads ||= []
+
+      super(params)
+    end
+
+    # convert bids to GoogleApi format
+    #
+    # can be either string (just xsi_type) or hash (xsi_type with params)
+    # although I'm not sure if just string makes sense in this case
+    #
+    def bids=(params = {})
+      @bids = params
+
       if @bids
         unless @bids.is_a?(Hash)
           @bids = { :xsi_type => @bids }
@@ -42,11 +60,6 @@ module Adapi
           end
         end
       end
-
-      @keywords ||= []
-      @ads ||= []
-
-      super(params)
     end
 
     def create
@@ -90,22 +103,98 @@ module Adapi
 
       true
     end
+
+    def update(params = {})
+      # step 1. update core attributes
+      core_attributes = [ :id, :campaign_id, :name, :status, :bids ]
+      # get operand in google format 
+      # parse the given params by initialize method...
+      ad_group = Adapi::AdGroup.new(params)
+      # HOTFIX remove :service_name param inserted by initialize method
+      params.delete(:service_name)
+      # ...and load parsed params back into the hash
+      core_params = Hash[ core_attributes.map { |k| [k, ad_group.send(k)] if params[k].present? }.compact ]
+
+      response = ad_group.mutate(
+        :operator => 'SET', 
+        :operand => core_params.merge( :id => @id, :campaign_id => @campaign_id )
+      )
+
+      return false unless (response and response[:value])
+
+      # step 2. update keywords
+      # delete everything and create new keywords
+      if params[:keywords] and not params[:keywords].empty?
+        # delete existing keywords
+        # OPTIMIZE should be all in one request
+        Keyword.find(:all, :ad_group_id => @id).keywords.each do |keyword|
+          Keyword.new(:ad_group_id => @id).delete(keyword[:text][:criterion][:id])
+        end
+
+        # create new keywords
+        result = Adapi::Keyword.create(
+          :ad_group_id => @id,
+          :keywords => params[:keywords]
+        )
+        
+        unless result.errors.empty?
+          self.errors.add("Keyword", result.errors.to_a)
+          return false 
+        end
+      end
+
+      # step 3. update ads
+      # ads can't be updated, gotta remove them all and add new ads
+      if params[:ads] and not params[:ads].empty?
+        # remove all existing ads
+        self.find_ads.each do |ad| 
+          unless ad.destroy
+            self.errors.add("Ad \"#{ad.headline}\"", ["cannot be deleted"])
+            return false 
+          end
+        end
+
+        # create new ads
+        params[:ads].each do |ad|
+          ad = Adapi::Ad::TextAd.create( ad.merge(:ad_group_id => @id) )
+
+          unless ad.errors.empty?
+            self.errors.add("Ad \"#{ad.headline}\"", ad.errors.to_a)
+            return false 
+          end
+        end
+      end
+
+      true
+    end
  
+    # PS: perhaps also change the ad_group name when deleting
+    def delete
+      update(:status => 'DELETED')  
+    end
+
     def self.find(amount = :all, params = {})
       params.symbolize_keys!
       first_only = (amount.to_sym == :first)
+      # by default, exclude ad_groups with status DELETED
+      params[:status] ||= %w{ ENABLED PAUSED }
 
       raise "Campaign ID is required" unless params[:campaign_id]
       
-      predicates = [ :campaign_id, :id ].map do |param_name|
-        if params[param_name]
-          value = Array.try_convert(params[param_name]) ? params_param_name : [params[param_name]]
-          {:field => param_name.to_s.camelcase, :operator => 'IN', :values => value }
+      predicates = [ :campaign_id, :id, :name, :status ].map do |param_name|
+        if params[param_name].present?
+          {:field => param_name.to_s.camelcase, :operator => 'IN', :values => Array( params[param_name] ) }
         end
       end.compact
 
+      select_fields = %w{ Id CampaignId Name Status } 
+      # add Bids atributes
+      select_fields += %w{ EnhancedCpcEnabled 
+        ProxyKeywordMaxCpc ProxySiteMaxCpc 
+        KeywordMaxCpc KeywordContentMaxCpc }
+
       selector = {
-        :fields => ['Id', 'Name', 'Status'],
+        :fields => select_fields,
         :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
         :predicates => predicates
       }
@@ -124,6 +213,8 @@ module Adapi
         )
       end
 
+      ad_groups.map! { |ad_group| AdGroup.new(ad_group) }
+
       first_only ? ad_groups.first : ad_groups
     end
 
@@ -136,16 +227,5 @@ module Adapi
       Ad::TextAd.find( (first_only ? :first : :all), :ad_group_id => self.id )
     end
 
-    # Converts ad group data to hash - of the same structure which is used when
-    # creating an ad group.
-    #
-    def to_hash
-      ad_group_hash = {
-        :id => self[:id],
-        :name => self[:name],
-        :status => self[:status]
-      }
-    end
-
   end
 end