adapi 0.0.9 → 0.1.0

data/examples/add_keywords.rb

@@ -10,17 +10,28 @@ $keywords = Adapi::Keyword.new(
   :keywords => [ 'dem codez', '"top coder"', '[-code]' ]
 )
 
-$r = $keywords.create
+$keywords.create
 
-# get array of keywords from Keyword instance
-$google_keywords = Adapi::Keyword.find(:all, :ad_group_id => $ad_group[:id]).keywords
+if $keywords.errors.any?
 
-$params_keywords = Adapi::Keyword.parameterized($google_keywords)
+  puts "\nERRORS:"
+  pp $keywords.errors.messages
 
-$short_keywords = Adapi::Keyword.shortened($google_keywords)
+else
 
-p "PARAMS:"
-pp $params_keywords
+  puts "\nKEYWORDS CREATED\n"
 
-p "\nSHORT:"
-pp $short_keywords
+  # get array of keywords from Keyword instance
+  $google_keywords = Adapi::Keyword.find(:all, :ad_group_id => $ad_group[:id]).keywords
+
+  $params_keywords = Adapi::Keyword.parameterized($google_keywords)
+
+  $short_keywords = Adapi::Keyword.shortened($google_keywords)
+
+  puts "DETAILED:"
+  pp $params_keywords
+
+  puts "\nSHORT:"
+  pp $short_keywords
+
+end

data/examples/add_text_ads.rb

@@ -0,0 +1,45 @@
+
+require 'adapi'
+
+require_relative 'add_bare_ad_group'
+
+$ad = Adapi::Ad::TextAd.create( :ads => [
+  {
+    :ad_group_id => $ad_group[:id],
+    :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',
+    :status => 'PAUSED'
+  },
+
+  {
+    :ad_group_id => $ad_group[:id],
+    :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',
+    :status => 'PAUSED'
+  },
+
+  {
+    :ad_group_id => $ad_group[:id],
+    :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',
+    :status => 'PAUSED'
+  }
+] )
+
+puts "\nCREATED ADS FOR AD GROUP #{$ad_group[:id]}:"
+
+$ads = Adapi::Ad::TextAd.find( :all, :ad_group_id => $ad_group[:id] )
+
+$ads.each_with_index do |ad, i|
+  puts "\nAD NR. #{i + 1}:"
+  pp ad.attributes
+end

data/examples/rollback_campaign.rb

@@ -2,24 +2,21 @@
 
 require 'adapi'
 
-# This test tries to create a complete campaign and fails because ad is
-# intentionally left without url. The point is to test how create_campaign
-# fails: campaign status should be set to DELETED and name changed (so the
-# name isn't blocked and another campaign can be created with the same name
-# eventually)
+# Tries to create a campaign and fails because ad is intentionally left 
+# without url. We test if campaign then rollbacks correctly:
+# * status should be set to DELETED 
+# * renamed so the original campaign name isn't blocked
 
 campaign_data = {
   :name => "Campaign #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'PAUSED',
-  # Automatic CPC: BudgetOptimizer or ManualCPC
   :bidding_strategy => { :xsi_type => 'BudgetOptimizer', :bid_ceiling => 100 },
   :budget => { :amount => 50, :delivery_method => 'STANDARD' },
 
   :network_setting => {
     :target_google_search => true,
     :target_search_network => true,
-    :target_content_network => false,
-    :target_content_contextual => false
+    :target_content_network => false
   },
 
   :criteria => {
@@ -47,12 +44,38 @@ campaign_data = {
   ]
 
 }
- 
+
 $campaign = Adapi::Campaign.create(campaign_data)
 
-p "Campaign ID #{$campaign.id} created"
-p "with status DELETED and changed name"
-pp $campaign.attributes
+unless $campaign.errors.empty?
+
+  puts "\nERRORS WHEN UPDATING CAMPAIGN #{$campaign.id}:"
+  pp $campaign.errors.full_messages
+
+  puts "\nROLLBACKING CAMPAIGN #{$campaign.id}\n"
+
+  $campaign.rollback!
+
+  unless $campaign.errors.empty?
+
+    puts "\nERRORS WHEN ROLLBACKING CAMPAIGN #{$campaign.id}:"
+    pp $campaign.errors.full_messages
+
+  else
+
+    puts "\nOK, ROLLBACKED CAMPAIGN #{$campaign.id}"
+
+    $campaign = Adapi::Campaign.find($campaign.id)
+
+    puts "\nCAMPAIGN DATA:"
+    pp $campaign.attributes
+
+  end
+
+else
+
+  puts "\nCREATED CAMPAIGN #{$campaign.id}"
+
+  puts "\nSOMETHING IS WRONG, THIS SHOULDN'T HAPPEN!"
 
-p "with errors:"
-pp $campaign.errors.to_a
+end

data/examples/update_campaign.rb

@@ -12,11 +12,7 @@ $campaign = Adapi::Campaign.update(
   :network_setting => {
     :target_google_search => false,
     :target_search_network => false,
-    :target_content_network => true,
-    :target_content_contextual => true
-    # FIXME returns error which is not trapped:
-    # TargetError.CANNOT_TARGET_PARTNER_SEARCH_NETWORK 
-    # :target_partner_search_network => true
+    :target_content_network => true
   },
 
   # deletes all criteria (except :platform) and create these new ones

data/examples/update_complete_campaign.rb

@@ -19,8 +19,7 @@ campaign_data = {
   :network_setting => {
     :target_google_search => true,
     :target_search_network => true,
-    :target_content_network => false,
-    :target_content_contextual => false
+    :target_content_network => false
   },
 
   :criteria => {
@@ -82,7 +81,7 @@ p "Created campaign ID #{$campaign.id}"
 # * change second ad_group
 # * add new ad_group
 
-Adapi::Campaign.update(
+$campaign.update(
   :id => $campaign[:id],
   :status => 'ACTIVE',
   :name => "UPDATED #{$campaign[:name]}",
@@ -171,7 +170,7 @@ else
   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
+    pp ad_group
   end
 
 end

data/lib/adapi.rb

@@ -2,15 +2,16 @@
 
 require 'rubygems'
 require 'adwords_api'
-# TODO use for optional logging of general activity
-# currently we only load communication with adwords-api
-# in form of complete SOAP requests
+# provides various utility methods
+require 'adwords_api/utils'
+# TODO log of general activity (currently log only SOAP requests)
 # require 'logger'
 require 'yaml'
 require 'pp'
 
 require 'active_model'
 # load only ActiveSupport core extensions
+# TODO require only parts that are really needed
 require 'active_support/core_ext'
 
 require 'adapi/version'
@@ -44,7 +45,7 @@ HTTPI.adapter = :curb
 HTTPI.log = false # supress HTTPI output
 
 module Adapi
-  API_VERSION = :v201109_1
+  API_VERSION = :v201206
 end
 
 if RUBY_VERSION < '1.9'

data/lib/adapi/ad.rb

@@ -16,8 +16,7 @@ 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( 'id' => id, 'ad_group_id' => ad_group_id, 
-        '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 = {})
@@ -31,6 +30,7 @@ module Adapi
     end
 
     # deletes ad
+    # TODO call by delete method
     #
     def destroy
       response = self.mutate(
@@ -44,46 +44,21 @@ module Adapi
       (response and response[:value]) ? true : false
     end
 
-    # ad-specific mutate wrapper, deals with PolicyViolations for ads
-    #
-    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
+    # FIXME add validations
+    def delete(params = {})
+      operations = params[:ad_ids].map do |ad_id|
+        {
+          :operator => 'REMOVE',
+          :operand => {
+            :ad_group_id => params[:ad_group_id],
+            :ad => { :id => ad_id, :xsi_type => 'Ad' }
+          }
+        }
       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
+      response = self.mutate(operations)
 
-            # 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
+      (response and response[:value]) ? true : false
     end
 
   end

data/lib/adapi/ad/text_ad.rb

@@ -1,13 +1,17 @@
 # encoding: utf-8
 
 module Adapi
+  # http://code.google.com/apis/adwords/docs/reference/latest/AdGroupAdService.TextAd.html
+  #
   # Ad::TextAd == AdGroupAd::TextAd
   #
-  # http://code.google.com/apis/adwords/docs/reference/latest/AdGroupAdService.TextAd.html
+  # This model supports both individual and batch create/update of ads.
+  # If :ads parameter is not nil, it is considered as array of ads to
+  # be updated in batch.
   #
   class Ad::TextAd < Ad
 
-    ATTRIBUTES = [ :headline, :description1, :description2 ]
+    ATTRIBUTES = [ :headline, :description1, :description2, :ads ]
 
     attr_accessor *ATTRIBUTES
 
@@ -34,37 +38,48 @@ 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 => operand
+      @ads = [ self.attributes ] unless @ads 
+
+      operations = []
+
+      @ads.each do |ad_params|
+
+        ad = TextAd.new(ad_params)
+
+        operand = ad.attributes.delete_if do |k|
+          [ :campaign_id, :ad_group_id, :id, :status, :ads ].include?(k.to_sym)
+        end.symbolize_keys
+
+        operations << {
+          :operator => 'ADD',
+          :operand => {
+            :ad_group_id => ad.ad_group_id,
+            :status => ad.status,
+            :ad => operand
+          }
         }
-      }
+      end
 
-      response = self.mutate(operation)
+      self.mutate(operations)
 
       # 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 }
+      # do it only once. from my experience with AdWords API, multiple retries are bad practice
+      if self.errors[:PolicyViolationError].any?
+
+        self.errors[:PolicyViolationError].each do |e|
+          i = e.delete(:operation_index) 
+          operations[i][:exemption_requests] = [ { :key => e } ]
         end
 
         self.errors.clear
 
-        response = self.mutate(operation)
+        self.mutate(operations)
       end
 
-      return false unless self.errors.empty?
-          
-      # set ad id
-      self.id = response[:value].first[:ad][:id] rescue nil
+      return false if self.errors.any?
+
+      # FIXME return ids of newly created ads
+      # self.id = response[:value].first[:ad][:id] rescue nil
   
       true
     end

data/lib/adapi/ad_group.rb

@@ -50,7 +50,7 @@ module Adapi
         end
     
         # convert bid amounts to micro_amounts
-        [ :proxy_keyword_max_cpc, :proxy_site_max_cpc ].each do |k|          
+        [ :proxy_keyword_max_cpc ].each do |k|          
           if @bids[k] and not @bids[k].is_a?(Hash)
             @bids[k] = {
               :amount => {
@@ -76,7 +76,7 @@ module Adapi
         :operand => operand
       )
 
-      return false unless (response and response[:value])
+      check_for_errors(self)
       
       self.id = response[:value].first[:id] rescue nil
       
@@ -86,22 +86,19 @@ module Adapi
           :keywords => @keywords
         )
         
-        if (keyword.errors.size > 0)
-          self.errors.add("[keyword]", keyword.errors.to_a)
-          return false 
-        end
+        check_for_errors(keyword, :prefix => "Keyword")
       end
 
-      @ads.each do |ad_data|
-        ad = Adapi::Ad::TextAd.create( ad_data.merge(:ad_group_id => @id) )
+      if not @ads.empty?
+        ad = Adapi::Ad::TextAd.create( :ads => @ads.map { |ad_data| ad_data.merge(:ad_group_id => @id) } )
 
-        if (ad.errors.size > 0)
-          self.errors.add("[ad] \"#{ad.headline}\"", ad.errors.to_a)
-          return false 
-        end
+        check_for_errors(ad, :prefix => "Ad \"#{ad.headline}\"")
       end
 
-      true
+      self.errors.empty?
+
+    rescue AdGroupError => e
+      false
     end
 
     def update(params = {})
@@ -120,7 +117,7 @@ module Adapi
         :operand => core_params.merge( :id => @id, :campaign_id => @campaign_id )
       )
 
-      return false unless (response and response[:value])
+      check_for_errors(ad_group, :store_errors => false)
 
       # step 2. update keywords
       # delete everything and create new keywords
@@ -136,36 +133,45 @@ module Adapi
           :ad_group_id => @id,
           :keywords => params[:keywords]
         )
-        
-        unless result.errors.empty?
-          self.errors.add("Keyword", result.errors.to_a)
-          return false 
-        end
+
+        check_for_errors(result, :prefix => "Keyword")        
       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
+        # TODO change into class method
+        existing_ads = self.find_ads
+        ad = existing_ads.first.delete(
+          :ad_group_id => @id,
+          :ad_ids => existing_ads.map { |ad| ad.id }
+        )
+
+        unless ad
+          # REFACTOR
+          self.errors.add(:base, add.errors.full_messages)
+          return false 
+        end
+
+=begin
         self.find_ads.each do |ad| 
           unless ad.destroy
             self.errors.add("Ad \"#{ad.headline}\"", ["cannot be deleted"])
             return false 
           end
         end
-
+=end
         # create new ads
-        params[:ads].each do |ad|
-          ad = Adapi::Ad::TextAd.create( ad.merge(:ad_group_id => @id) )
+        ad = Adapi::Ad::TextAd.create( :ads => params[:ads].map { |ad_data| ad_data.merge(:ad_group_id => @id) } )
 
-          unless ad.errors.empty?
-            self.errors.add("Ad \"#{ad.headline}\"", ad.errors.to_a)
-            return false 
-          end
-        end
+        check_for_errors(ad, :prefix => "Ad \"#{ad.headline}\"")
       end
 
-      true
+      self.errors.empty?
+
+    rescue AdGroupError => e
+      false
     end
  
     # PS: perhaps also change the ad_group name when deleting
@@ -189,8 +195,7 @@ module Adapi
 
       select_fields = %w{ Id CampaignId Name Status } 
       # add Bids atributes
-      select_fields += %w{ EnhancedCpcEnabled 
-        ProxyKeywordMaxCpc ProxySiteMaxCpc 
+      select_fields += %w{ EnhancedCpcEnabled ProxyKeywordMaxCpc 
         KeywordMaxCpc KeywordContentMaxCpc }
 
       selector = {