Updating examples for Upgraded URLs.

mcloonan · mcloonan · commit 749e0f428681 · 2015-02-18T13:08:06.000-05:00
diff --git a/adwords_api/ChangeLog b/adwords_api/ChangeLog
@@ -1,3 +1,9 @@
+0.14.1:
+  - Corrected the comments and settings regarding target_all in add_ad_groups
+    examples.
+  - Added new example for migrating to Upgraded URLs.
+  - Updated examples to reference final URLs.
+
 0.14.0:
   - Removed deprecated API version v201402.
   - Removed support for returnMoneyInMicros header.
diff --git a/adwords_api/examples/v201406/advanced_operations/add_text_ad_with_upgraded_urls.rb b/adwords_api/examples/v201406/advanced_operations/add_text_ad_with_upgraded_urls.rb
@@ -62,7 +62,7 @@ def add_text_ad_with_upgraded_urls(ad_group_id)
     # Specify a tracking URL for 3rd party tracking provider. You may specify
     # one at customer, campaign, ad group, ad, criterion, or feed item levels.
     :tracking_url_template => 'http://tracker.example.com/' +
-        '?cid={_season}&promocode={_promocode}&u={lpurl}',
+        '?season={_season}&promocode={_promocode}&u={lpurl}',
     :url_custom_parameters => tracking_url_parameters,
     # Specify a list of final URLs. This field cannot be set if :url field
     # is set. This may be specified at ad, criterion, and feed item levels.
diff --git a/adwords_api/examples/v201406/basic_operations/add_ad_groups.rb b/adwords_api/examples/v201406/basic_operations/add_ad_groups.rb
@@ -53,22 +53,24 @@ def add_ad_groups(campaign_id)
         ]
       },
       :settings => [
-        # Targetting restriction settings - these setting only affect serving
+        # Targeting restriction settings - these settings only affect serving
         # for the Display Network.
         {
           :xsi_type => 'TargetingSetting',
           :details => [
             # Restricting to serve ads that match your ad group placements.
+            # This is equivalent to choosing "Target and bid" in the UI.
             {
               :xsi_type => 'TargetingSettingDetail',
               :criterion_type_group => 'PLACEMENT',
-              :target_all => true
+              :target_all => false
             },
-            # Using your ad group verticals only for bidding.
+            # Using your ad group verticals only for bidding. This is equivalent
+            # to choosing "Bid only" in the UI.
             {
               :xsi_type => 'TargetingSettingDetail',
               :criterion_type_group => 'VERTICAL',
-              :target_all => false
+              :target_all => true
             }
           ]
         }
diff --git a/adwords_api/examples/v201409/advanced_operations/add_ad_customizer.rb b/adwords_api/examples/v201409/advanced_operations/add_ad_customizer.rb
@@ -203,7 +203,7 @@ def add_ad_customizer(ad_group_ids)
     :headline => 'Luxury Cruise to {=CustomizerFeed.Name}',
     :description1 => 'Only {=CustomizerFeed.Price}',
     :description2 => 'Offer ends in {=countdown(CustomizerFeed.Date)}!',
-    :url => 'http://www.example.com',
+    :final_urls => ['http://www.example.com'],
     :display_url => 'www.example.com'
   }
 
diff --git a/adwords_api/examples/v201409/advanced_operations/add_click_to_download_ad.rb b/adwords_api/examples/v201409/advanced_operations/add_click_to_download_ad.rb
@@ -75,8 +75,8 @@ def add_click_to_download_ad(ad_group_id)
     :xsi_type => 'TemplateAd',
     :name => 'Ad for demo game',
     :template_id => 353,
-    :url =>
-        'http://play.google.com/store/apps/details?id=com.example.demogame',
+    :final_urls =>
+        ['http://play.google.com/store/apps/details?id=com.example.demogame'],
     :display_url => 'play.google.com',
     :template_elements => [ad_data]
   }
@@ -96,7 +96,7 @@ def add_click_to_download_ad(ad_group_id)
   if response and response[:value]
     response[:value].each do |ad|
       puts "Added new click-to-download ad to ad group ID %d with url '%s'." %
-          [ad[:ad][:id], ad[:ad][:url]]
+          [ad[:ad][:id], ad[:ad][:final_urls[0]]]
     end
   else
     raise StandardError, 'No ads were added.'
diff --git a/adwords_api/examples/v201409/advanced_operations/add_site_links.rb b/adwords_api/examples/v201409/advanced_operations/add_site_links.rb
@@ -60,24 +60,24 @@ def add_site_links(campaign_id)
     # Attribute of type STRING.
     link_text_feed_attribute_id = feed[:attributes][0][:id]
     # Attribute of type URL.
-    link_url_feed_attribute_id = feed[:attributes][1][:id]
+    final_url_feed_attribute_id = feed[:attributes][1][:id]
     # Attribute of type STRING.
     line_1_feed_attribute_id = feed[:attributes][2][:id]
     #Attribute of type STRING.
     line_2_feed_attribute_id = feed[:attributes][3][:id]
     puts "Feed with name '%s' and ID %d was added with" %
         [feed[:name], feed[:id]]
-    puts "\tText attribute ID %d and URL attribute ID %d " +
+    puts "\tText attribute ID %d and Final URL attribute ID %d " +
         "and Line 1 attribute ID %d and Line 2 attribute ID %d." % [
           link_text_feed_attribute_id,
-          link_url_feed_attribute_id,
+          final_url_feed_attribute_id,
           line_1_feed_attribute_id,
           line_2_feed_attribute_id
         ]
 
     sitelinks_data[:feed_id] = feed[:id]
     sitelinks_data[:link_text_feed_id] = link_text_feed_attribute_id
-    sitelinks_data[:link_url_feed_id] = link_url_feed_attribute_id
+    sitelinks_data[:final_url_feed_id] = final_url_feed_attribute_id
     sitelinks_data[:line_1_feed_id] = line_1_feed_attribute_id
     sitelinks_data[:line_2_feed_id] = line_2_feed_attribute_id
   else
@@ -133,7 +133,7 @@ def add_site_links(campaign_id)
           :string_value => item[:text]
         },
         {
-          :feed_attribute_id => sitelinks_data[:link_url_feed_id],
+          :feed_attribute_id => sitelinks_data[:final_url_feed_id],
           :string_value => item[:url]
         },
         {
@@ -173,8 +173,8 @@ def add_site_links(campaign_id)
         :field_id => PLACEHOLDER_FIELD_SITELINK_LINK_TEXT
       },
       {
-        :feed_attribute_id => sitelinks_data[:link_url_feed_id],
-        :field_id => PLACEHOLDER_FIELD_SITELINK_LINK_URL
+        :feed_attribute_id => sitelinks_data[:final_url_feed_id],
+        :field_id => PLACEHOLDER_FIELD_SITELINK_FINAL_URL
       },
       {
         :feed_attribute_id => sitelinks_data[:line_1_feed_id],
@@ -271,7 +271,7 @@ def add_site_links(campaign_id)
   #     https://developers.google.com/adwords/api/docs/appendix/placeholders
   PLACEHOLDER_SITELINKS = 1
   PLACEHOLDER_FIELD_SITELINK_LINK_TEXT = 1
-  PLACEHOLDER_FIELD_SITELINK_LINK_URL = 2
+  PLACEHOLDER_FIELD_SITELINK_FINAL_URL = 5
   PLACEHOLDER_FIELD_SITELINK_LINE_1_TEXT = 3
   PLACEHOLDER_FIELD_SITELINK_LINE_2_TEXT = 4
 
diff --git a/adwords_api/examples/v201409/advanced_operations/add_text_ad_with_upgraded_urls.rb b/adwords_api/examples/v201409/advanced_operations/add_text_ad_with_upgraded_urls.rb
@@ -18,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example adds a text ad that uses upgraded URLs. This example will only
-# work if your account is a test account or is whitelisted for this feature.
+# This code example adds a text ad that uses advanced features of upgraded
+# URLs.
 #
 # Tags: AdGroupAdService.mutate
 
@@ -62,7 +62,7 @@ def add_text_ad_with_upgraded_urls(ad_group_id)
     # Specify a tracking URL for 3rd party tracking provider. You may specify
     # one at customer, campaign, ad group, ad, criterion, or feed item levels.
     :tracking_url_template => 'http://tracker.example.com/' +
-        '?cid={_season}&promocode={_promocode}&u={lpurl}',
+        '?season={_season}&promocode={_promocode}&u={lpurl}',
     :url_custom_parameters => tracking_url_parameters,
     # Specify a list of final URLs. This field cannot be set if :url field
     # is set. This may be specified at ad, criterion, and feed item levels.
diff --git a/adwords_api/examples/v201409/basic_operations/add_ad_groups.rb b/adwords_api/examples/v201409/basic_operations/add_ad_groups.rb
@@ -53,22 +53,24 @@ def add_ad_groups(campaign_id)
         ]
       },
       :settings => [
-        # Targetting restriction settings - these setting only affect serving
+        # Targeting restriction settings - these settings only affect serving
         # for the Display Network.
         {
           :xsi_type => 'TargetingSetting',
           :details => [
             # Restricting to serve ads that match your ad group placements.
+            # This is equivalent to choosing "Target and bid" in the UI.
             {
               :xsi_type => 'TargetingSettingDetail',
               :criterion_type_group => 'PLACEMENT',
-              :target_all => true
+              :target_all => false
             },
-            # Using your ad group verticals only for bidding.
+            # Using your ad group verticals only for bidding. This is equivalent
+            # to choosing "Bid only" in the UI.
             {
               :xsi_type => 'TargetingSettingDetail',
               :criterion_type_group => 'VERTICAL',
-              :target_all => false
+              :target_all => true
             }
           ]
         }
diff --git a/adwords_api/examples/v201409/basic_operations/add_keywords.rb b/adwords_api/examples/v201409/basic_operations/add_keywords.rb
@@ -51,7 +51,7 @@ def add_keywords(ad_group_id)
      },
      # Optional fields:
      :user_status => 'PAUSED',
-     :destination_url => 'http://example.com/mars'
+     :final_urls => ['http://example.com/mars']
     },
     {:xsi_type => 'BiddableAdGroupCriterion',
      :ad_group_id => ad_group_id,
diff --git a/adwords_api/examples/v201409/basic_operations/add_text_ads.rb b/adwords_api/examples/v201409/basic_operations/add_text_ads.rb
@@ -46,15 +46,15 @@ def add_text_ads(ad_group_id)
       :headline => 'Luxury Cruise to Mars',
       :description1 => 'Visit the Red Planet in style.',
       :description2 => 'Low-gravity fun for everyone!',
-      :url => 'http://www.example.com',
+      :final_urls => ['http://www.example.com'],
       :display_url => 'www.example.com'
     },
     {
       :xsi_type => 'TextAd',
       :headline => 'Luxury Cruise to Mars',
       :description1 => 'Enjoy your stay at Red Planet.',
       :description2 => 'Buy your tickets now!',
-      :url => 'http://www.example.com',
+      :final_urls => ['http://www.example.com'],
       :display_url => 'www.example.com'
     }
   ]
diff --git a/adwords_api/examples/v201409/campaign_management/set_ad_parameters.rb b/adwords_api/examples/v201409/campaign_management/set_ad_parameters.rb
@@ -50,7 +50,7 @@ def set_ad_parameters(ad_group_id, criterion_id)
         :headline => 'Luxury Mars Cruises',
         :description1 => 'Low-gravity fun for {param1:cheap}.',
         :description2 => 'Only {param2:a few} seats left!',
-        :url => 'http://www.example.com',
+        :final_urls => ['http://www.example.com'],
         :display_url => 'www.example.com'
       }
     }
diff --git a/adwords_api/examples/v201409/campaign_management/validate_text_ad.rb b/adwords_api/examples/v201409/campaign_management/validate_text_ad.rb
@@ -49,7 +49,7 @@ def validate_text_ad(ad_group_id)
         :headline => 'Luxury Cruise to Mars',
         :description1 => 'Visit the Red Planet in style.',
         :description2 => 'Low-gravity fun for everyone!',
-        :url => 'http://www.example.com',
+        :final_urls => ['http://www.example.com'],
         :display_url => 'www.example.com'
       }
     }
diff --git a/adwords_api/examples/v201409/error_handling/handle_policy_violation_error.rb b/adwords_api/examples/v201409/error_handling/handle_policy_violation_error.rb
@@ -50,7 +50,7 @@ def handle_policy_violation_error(ad_group_id)
         :headline => 'Mars Cruise!!!',
         :description1 => 'Visit the Red Planet in style.',
         :description2 => 'Low-gravity fun for everyone!',
-        :url => 'http://www.example.com',
+        :final_urls => ['http://www.example.com'],
         :display_url => 'www.example.com',
       }
     }
diff --git a/adwords_api/examples/v201409/migration/upgrade_ad_url.rb b/adwords_api/examples/v201409/migration/upgrade_ad_url.rb
@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.mcloonan@gmail.com (Michael Cloonan)
+#
+# Copyright:: Copyright 2015, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This code example upgrades an ad to use upgraded URLs.
+#
+# Tags: AdGroupAdService.get, AdGroupAdService.upgradeUrl
+
+require 'adwords_api'
+
+def upgrade_ad_url(ad_group_id, ad_id)
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
+
+  selector = {
+    :fields => ['Id', 'Url'],
+    :predicates => [
+      {:field => 'AdGroupId', :operator => 'EQUALS', :values => [ad_group_id]},
+      {:field => 'Id', :operator => 'EQUALS', :values => [ad_id]}
+    ]
+  }
+
+  page = ad_group_ad_srv.get(selector)
+  ad_group_ad = page[:entries][0] if page[:entries]
+
+  raise StandardError, "Ad not found." if ad_group_ad.nil?
+
+  ad_url_upgrade = {
+    :ad_id => ad_group_ad[:ad][:id],
+    :final_url => ad_group_ad[:ad][:url]
+  }
+
+  response = ad_group_ad_srv.upgrade_url([ad_url_upgrade])
+  if response
+    ad_group_ad = response.first
+    puts "Ad with ID %d and destination url '%s' was upgraded." %
+        [ad_group_ad[:id], ad_group_ad[:final_urls].first]
+  else
+    raise StandardError, 'failed to upgrade ads.'
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201409
+
+  begin
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+    ad_id = 'INSERT_AD_ID_HERE'.to_i
+    upgrade_ad_url(ad_group_id, ad_id)
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'http://code.google.com/p/google-api-ads-ruby/wiki/OAuth2'
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end
diff --git a/adwords_api/examples/v201409/reporting/download_criteria_report.rb b/adwords_api/examples/v201409/reporting/download_criteria_report.rb
@@ -38,7 +38,7 @@ def download_criteria_report(file_name)
   report_definition = {
     :selector => {
       :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
-          'Impressions', 'Clicks', 'Cost'],
+          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
       # Predicates are optional.
       :predicates => {
         :field => 'Status',
diff --git a/adwords_api/lib/adwords_api/api_config.rb b/adwords_api/lib/adwords_api/api_config.rb
@@ -250,14 +250,6 @@ def self.subdir_config
       @@subdir_config
     end
 
-    def self.client_login_config(key)
-      raise AdsCommon::Errors::AuthError,
-            "ClientLogin is not supported. " +
-            "Please use OAuth2 instead. See here for details:\n\t\t" +
-            "https://developers.google.com/adwords/api/" +
-            "docs/guides/authentication"
-    end
-
     def self.default_config_filename
       DEFAULT_CONFIG_FILENAME
     end
diff --git a/adwords_api/lib/adwords_api/version.rb b/adwords_api/lib/adwords_api/version.rb
@@ -21,6 +21,6 @@
 
 module AdwordsApi
   module ApiConfig
-    CLIENT_LIB_VERSION = '0.14.0'
+    CLIENT_LIB_VERSION = '0.14.1'
   end
 end

Original file line number	Diff line number	Diff line change
`@@ -53,22 +53,24 @@ def add_ad_groups(campaign_id)`
`53`	`53`	`]`
`54`	`54`	`},`
`55`	`55`	`:settings => [`
`56`		`- # Targetting restriction settings - these setting only affect serving`
	`56`	`+ # Targeting restriction settings - these settings only affect serving`
`57`	`57`	`# for the Display Network.`
`58`	`58`	`{`
`59`	`59`	`:xsi_type => 'TargetingSetting',`
`60`	`60`	`:details => [`
`61`	`61`	`# Restricting to serve ads that match your ad group placements.`
	`62`	`+ # This is equivalent to choosing "Target and bid" in the UI.`
`62`	`63`	`{`
`63`	`64`	`:xsi_type => 'TargetingSettingDetail',`
`64`	`65`	`:criterion_type_group => 'PLACEMENT',`
`65`		`- :target_all => true`
	`66`	`+ :target_all => false`
`66`	`67`	`},`
`67`		`- # Using your ad group verticals only for bidding.`
	`68`	`+ # Using your ad group verticals only for bidding. This is equivalent`
	`69`	`+ # to choosing "Bid only" in the UI.`
`68`	`70`	`{`
`69`	`71`	`:xsi_type => 'TargetingSettingDetail',`
`70`	`72`	`:criterion_type_group => 'VERTICAL',`
`71`		`- :target_all => false`
	`73`	`+ :target_all => true`
`72`	`74`	`}`
`73`	`75`	`]`
`74`	`76`	`}`
Original file line number	Diff line number	Diff line change
`@@ -203,7 +203,7 @@ def add_ad_customizer(ad_group_ids)`
`203`	`203`	`:headline => 'Luxury Cruise to {=CustomizerFeed.Name}',`
`204`	`204`	`:description1 => 'Only {=CustomizerFeed.Price}',`
`205`	`205`	`:description2 => 'Offer ends in {=countdown(CustomizerFeed.Date)}!',`
`206`		`- :url => 'http://www.example.com',`
	`206`	`+ :final_urls => ['http://www.example.com'],`
`207`	`207`	`:display_url => 'www.example.com'`
`208`	`208`	`}`
`209`	`209`
Original file line number	Diff line number	Diff line change
`@@ -46,15 +46,15 @@ def add_text_ads(ad_group_id)`
`46`	`46`	`:headline => 'Luxury Cruise to Mars',`
`47`	`47`	`:description1 => 'Visit the Red Planet in style.',`
`48`	`48`	`:description2 => 'Low-gravity fun for everyone!',`
`49`		`- :url => 'http://www.example.com',`
	`49`	`+ :final_urls => ['http://www.example.com'],`
`50`	`50`	`:display_url => 'www.example.com'`
`51`	`51`	`},`
`52`	`52`	`{`
`53`	`53`	`:xsi_type => 'TextAd',`
`54`	`54`	`:headline => 'Luxury Cruise to Mars',`
`55`	`55`	`:description1 => 'Enjoy your stay at Red Planet.',`
`56`	`56`	`:description2 => 'Buy your tickets now!',`
`57`		`- :url => 'http://www.example.com',`
	`57`	`+ :final_urls => ['http://www.example.com'],`
`58`	`58`	`:display_url => 'www.example.com'`
`59`	`59`	`}`
`60`	`60`	`]`