google-adwords-api 0.14.2 → 0.15.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTA0OTUyODk0YzVjYmQxODJjNmE4OTRhNWM4Zjc5ZmQ1ZWIzNDVmMQ==
+    N2IwZjhmNzIxODY2YjM2YzgyY2NiNWVmNWM1OGNmODQwNTBlNzEyNg==
   data.tar.gz: !binary |-
-    MjQxMzZiODY5MzFkNTQ2MDAzNmM3ZGJmMmE5MWNmYjQ1YzFhMDVlMg==
+    NjkyNDVkMTVjZTg1MWZmZmFjYTI2ZjExMjQ0ZjAzOTgyYzU3ZmZlYw==
 SHA512:
   metadata.gz: !binary |-
-    NmQ5MDQzZDgxYmQwOGY3NGEwY2FiZTU4ODA5ZGQ5ZGMyZDBiZjI1ZWNjOTE5
-    ZTYyZTc5NTIwMmIxM2MwYzNjNjVmMmQ0M2Q4Y2YzZTg2NjA3YmY5OWIzZDlm
-    MjE0ZTk2N2UzMmViYTc0YTM4MTg5NWEzNmEwMDdmNjkxYTBmZjE=
+    NmNiODQ0MzNjMDJlZjZjMTNlYWZiZWMzYWVmN2ZmMjJkZmE3Y2IzNTM2NzE2
+    MzZkMWNjNDJiNDAxNTFhZTNjNjNjNTkxZDZlODg5NWQ2N2E1MzM4YzJmNmY1
+    MTNlNWMxZjhiNGE3NTYzNWRmOTExNzVlZWJmZmU4OTY4ZTkxZWM=
   data.tar.gz: !binary |-
-    Y2UxMjAyOGM3YmMwNmRiMjVjOWY5OGExMDAyM2YyMzUzMDNlYWZiYTJmODY3
-    MTczNTdhNzQwZTY1Yjk3YTQwYzZjNWNiMWUzMzYwOWI2NjE5MWQ4NzQ0MzBm
-    ZmM1YTIxOTg2ZjkxZTA1YWQ2ODEzYzE4MTk4YTIyNjRmYjdiYjA=
+    MTU0NTgxMDhjNTNjOTA0MDEyZTJjZGFlMDU2OWRhNDYwOWRlYzA4YzMyZGMx
+    MGIwYjFkMTFiZWY3MGE3YzcxNDk2ZDZhZjcyYzE0ZGIyMDE4YTkxMzkzMjE1
+    NDhmMDA4M2UwNDI1YWJlNWY5N2Y3NWNiOGUwYjAzYjI2Nzc0NmQ=

data/ChangeLog

@@ -1,5 +1,12 @@
+0.15.0:
+  - Removed deprecated API version v201406.
+  - Updated Feeds migration example to account for platform restrictions.
+  - Added support for skipping column header option in reporting.
+  - Reworked add sitelinks example for final URLs and functionString.
+
 0.14.2:
   - Support and examples for v201502.
+  - Added support for skipping report header and summary options.
 
 0.14.1:
   - Corrected the comments and settings regarding target_all in add_ad_groups

data/README.md

@@ -74,7 +74,7 @@ The basics of making a request are:
 
  3. Specify which service you're looking to use, and which version:
 
-        campaign_srv = adwords.service(:CampaignService, :v201406)
+        campaign_srv = adwords.service(:CampaignService, :v201502)
 
  4. You should now be able to just use the API methods in the returned object:
 
@@ -211,7 +211,7 @@ To target a specific version:
 
 For example:
 
-    $ rake generate[v201406]
+    $ rake generate[v201502]
 
 To target a specific service in a specific version:
 
@@ -219,7 +219,7 @@ To target a specific service in a specific version:
 
 For example:
 
-    $ rake generate[v201406,CampaignService]
+    $ rake generate[v201502,CampaignService]
 
 To build the gems:
 

data/adwords_api.yml

@@ -41,4 +41,9 @@
   # the URL, e.g.: http://user:password@proxy_hostname:8080
   # :proxy: INSERT_PROXY_HERE
 :library:
+  # Optional: set the log level.
   :log_level: INFO
+  # Optional: uncomment to skip header / summary rows in reporting.
+  #:skip_report_header: true
+  #:skip_report_summary: true
+  #:skip_column_header: true

data/examples/v201409/account_management/get_account_hierarchy.rb

@@ -45,8 +45,8 @@ def get_account_hierarchy()
     :fields => ['CustomerId',  'Name']
   }
 
-  # Run the request at the MCC level.
-  graph = adwords.use_mcc() {managed_customer_srv.get(selector)}
+  # Run the request. Make sure the configured clientCustomerId is an MCC.
+  graph = managed_customer_srv.get(selector)
 
   if graph and graph[:entries]
     puts 'Accounts under this hierarchy: %d' % graph[:total_num_entries]

data/examples/v201409/advanced_operations/{add_ad_customizer.rb → add_ad_customizers.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.mcloonan@gmail.com (Michael Cloonan)
 #
-# Copyright:: Copyright 2014, Google Inc. All Rights Reserved.
+# 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.
@@ -27,7 +27,7 @@
 
 require 'adwords_api'
 
-def add_ad_customizer(ad_group_ids)
+def add_ad_customizers(ad_group_ids)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -214,7 +214,7 @@ def add_ad_customizer(ad_group_ids)
       :operator => 'ADD',
       :operand => {
         :ad_group_id => ad_group_id,
-        :ad => text_ad
+        :ad => text_ad.dup()
       }
     }
   end
@@ -249,7 +249,7 @@ if __FILE__ == $0
         'INSERT_AD_GROUP_ID_HERE'.to_i,
         'INSERT_AD_GROUP_ID_HERE'.to_i
     ]
-    add_ad_customizer(ad_group_ids)
+    add_ad_customizers(ad_group_ids)
 
   # Authorization error.
   rescue AdsCommon::Errors::OAuth2VerificationRequired => e

data/examples/v201409/extensions/add_site_links_using_feeds.rb

@@ -46,7 +46,7 @@ def add_site_links(campaign_id)
     :name => 'Feed For Site Links',
     :attributes => [
       {:type => 'STRING', :name => 'Link Text'},
-      {:type => 'URL', :name => 'Link URL'},
+      {:type => 'URL_LIST', :name => 'Final URLs'},
       {:type => 'STRING', :name => 'Line 1 Description'},
       {:type => 'STRING', :name => 'Line 2 Description'}
     ]
@@ -59,7 +59,7 @@ def add_site_links(campaign_id)
     feed = response[:value].first
     # Attribute of type STRING.
     link_text_feed_attribute_id = feed[:attributes][0][:id]
-    # Attribute of type URL.
+    # Attribute of type URL_LIST.
     final_url_feed_attribute_id = feed[:attributes][1][:id]
     # Attribute of type STRING.
     line_1_feed_attribute_id = feed[:attributes][2][:id]
@@ -67,7 +67,7 @@ def add_site_links(campaign_id)
     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 Final URL attribute ID %d " +
+    puts "\tText attribute ID %d and Final URLs attribute ID %d " +
         "and Line 1 attribute ID %d and Line 2 attribute ID %d." % [
           link_text_feed_attribute_id,
           final_url_feed_attribute_id,
@@ -88,37 +88,37 @@ def add_site_links(campaign_id)
   items_data = [
     {
       :text => 'Home',
-      :url => 'http://www.example.com',
+      :final_urls => ['http://www.example.com'],
       :line_1 => 'Home line 1',
       :line_2 => 'Home line 2'
     },
     {
       :text => 'Stores',
-      :url => 'http://www.example.com/stores',
+      :final_urls => ['http://www.example.com/stores'],
       :line_1 => 'Stores line 1',
       :line_2 => 'Stores line 2'
      },
     {
       :text => 'On Sale',
-      :url => 'http://www.example.com/sale',
+      :final_urls => ['http://www.example.com/sale'],
       :line_1 => 'On Sale line 1',
       :line_2 => 'On Sale line 2'
     },
     {
       :text => 'Support',
-      :url => 'http://www.example.com/support',
+      :final_urls => ['http://www.example.com/support'],
       :line_1 => 'Support line 1',
       :line_2 => 'Support line 2'
     },
     {
       :text => 'Products',
-      :url => 'http://www.example.com/products',
+      :final_urls => ['http://www.example.com/products'],
       :line_1 => 'Products line 1',
       :line_2 => 'Products line 2'
     },
     {
       :text => 'About',
-      :url => 'http://www.example.com/about',
+      :final_urls => ['http://www.example.com/about'],
       :line_1 => 'About line 1',
       :line_2 => 'About line 2'
     }
@@ -134,7 +134,7 @@ def add_site_links(campaign_id)
         },
         {
           :feed_attribute_id => sitelinks_data[:final_url_feed_id],
-          :string_value => item[:url]
+          :string_values => item[:final_urls]
         },
         {
           :feed_attribute_id => sitelinks_data[:line_1_feed_id],
@@ -174,7 +174,7 @@ def add_site_links(campaign_id)
       },
       {
         :feed_attribute_id => sitelinks_data[:final_url_feed_id],
-        :field_id => PLACEHOLDER_FIELD_SITELINK_FINAL_URL
+        :field_id => PLACEHOLDER_FIELD_SITELINK_FINAL_URLS
       },
       {
         :feed_attribute_id => sitelinks_data[:line_1_feed_id],
@@ -271,7 +271,7 @@ if __FILE__ == $0
   #     https://developers.google.com/adwords/api/docs/appendix/placeholders
   PLACEHOLDER_SITELINKS = 1
   PLACEHOLDER_FIELD_SITELINK_LINK_TEXT = 1
-  PLACEHOLDER_FIELD_SITELINK_FINAL_URL = 5
+  PLACEHOLDER_FIELD_SITELINK_FINAL_URLS = 5
   PLACEHOLDER_FIELD_SITELINK_LINE_1_TEXT = 3
   PLACEHOLDER_FIELD_SITELINK_LINE_2_TEXT = 4
 

data/examples/v201409/migration/migrate_to_extension_settings.rb

@@ -64,13 +64,15 @@ def migrate_to_extension_settings()
         next
       end
 
+      platform_restrictions = get_platform_restrictions(campaign_feed)
+
       # Delete the campaign feed that associates the sitelinks from the
       # feed to the campaign.
       delete_campaign_feed(adwords, campaign_feed)
 
       # Create extension settings instead of sitelinks.
       create_extension_setting(adwords, feed_items, campaign_feed,
-          feed_item_ids)
+          feed_item_ids, platform_restrictions)
 
       # Mark the sitelinks from the feed for deletion.
       feed_item_ids
@@ -201,6 +203,26 @@ def get_feed_items(adwords, feed)
   return feed_items
 end
 
+def get_platform_restrictions(campaign_feed)
+  platform_restrictions = nil
+
+  if campaign_feed[:matching_function][:operator] == 'AND'
+    campaign_feed[:matching_function][:lhs_operand].each do |argument|
+      # Check if matchingFunction is EQUALS(CONTEXT.DEVICE, 'Mobile')
+      if argument[:value][:operator] == 'EQUALS'
+        request_context_operand = argument[:value][:lhs_operand].first()
+        if request_context_operand &&
+            request_context_operand == 'DEVICE_PLATFORM'
+          platform_restrictions =
+              argument[:value][:rhs_operand].first().upcase()
+          break
+        end
+      end
+    end
+  end
+  return platform_restrictions
+end
+
 def delete_old_feed_items(adwords, feed_item_ids, feed)
   return if feed_item_ids.empty?
 
@@ -219,7 +241,8 @@ def delete_old_feed_items(adwords, feed_item_ids, feed)
   feed_item_srv.mutate(operations)
 end
 
-def create_extension_setting(adwords, feed_items, campaign_feed, feed_item_ids)
+def create_extension_setting(
+    adwords, feed_items, campaign_feed, feed_item_ids, platform_restrictions)
   campaign_extension_setting_srv = adwords.service(
       :CampaignExtensionSettingService, API_VERSION)
 
@@ -254,6 +277,10 @@ def create_extension_setting(adwords, feed_items, campaign_feed, feed_item_ids)
     :extensions => extension_feed_items
   }
 
+  unless platform_restrictions.nil?
+    extension_setting[:platform_restrictions] = platform_restrictions
+  end
+
   campaign_extension_setting = {
     :campaign_id => campaign_feed[:campaign_id],
     :extension_type => 'SITELINK',

data/examples/v201409/reporting/parallel_report_download.rb

@@ -47,7 +47,7 @@ def parallel_report_download()
   selector = {:fields => ['CustomerId']}
 
   # Run the request at the MCC level.
-  graph = adwords.use_mcc() {managed_customer_srv.get(selector)}
+  graph = managed_customer_srv.get(selector)
 
   # Using queue to balance load between threads.
   queue = Queue.new()

data/examples/v201502/advanced_operations/{add_ad_customizer.rb → add_ad_customizers.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.mcloonan@gmail.com (Michael Cloonan)
 #
-# Copyright:: Copyright 2014, Google Inc. All Rights Reserved.
+# 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.
@@ -18,16 +18,16 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example adds an ad customizer feed and associates it with the customer.
-# Then it adds an ad that uses the feed to populate dynamic data.
+# This example adds an ad customizer feed using Extension Services. Then it adds
+# an ad that uses the feed to populate dynamic data.
 #
-# Tags: CustomerFeedService.mutate, FeedItemService.mutate
-# Tags: FeedMappingService.mutate, FeedService.mutate
+# Tags: AdCustomizerFeedService.mutate, FeedItemService.mutate
 # Tags: AdGroupAdService.mutate
 
 require 'adwords_api'
+require 'date'
 
-def add_ad_customizer(ad_group_ids)
+def add_ad_customizers(feed_name, ad_group_ids)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -36,95 +36,26 @@ def add_ad_customizer(ad_group_ids)
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  feed_srv = adwords.service(:FeedService, API_VERSION)
   feed_item_srv = adwords.service(:FeedItemService, API_VERSION)
-  feed_mapping_srv = adwords.service(:FeedMappingService, API_VERSION)
-  customer_feed_srv = adwords.service(:CustomerFeedService, API_VERSION)
   ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
 
-  # First, create a customizer feed. One feed per account can be used for
-  # all ads.
-  customizer_feed = {
-    :name => 'CustomizerFeed',
-    :attributes => [
-      {:type => 'STRING', :name => 'Name'},
-      {:type => 'STRING', :name => 'Price'},
-      {:type => 'DATE_TIME', :name => 'Date'}
-    ]
-  }
-
-  response = feed_srv.mutate([
-      {:operator => 'ADD', :operand => customizer_feed}
-  ])
-
-  feed_data = {}
-  if response and response[:value]
-    feed = response[:value].first
-    feed_data = {
-        :feed_id => feed[:id],
-        :name_id => feed[:attributes][0][:id],
-        :price_id => feed[:attributes][1][:id],
-        :date_id => feed[:attributes][2][:id]
-    }
-    puts "Feed with name '%s' and ID %d was added with:" %
-        [feed[:name], feed[:id]]
-    puts ("\tName attribute ID %d and price attribute ID %d " +
-        "and date attribute ID %d.") % [
-          feed_data[:name_id],
-          feed_data[:price_id],
-          feed_data[:date_id]
-        ]
-  else
-    raise new StandardError, 'No feeds were added.'
-  end
-
-  # Creating feed mapping to map the fields with customizer IDs.
-  feed_mapping = {
-    :placeholder_type => PLACEHOLDER_AD_CUSTOMIZER,
-    :feed_id => feed_data[:feed_id],
-    :attribute_field_mappings => [
-      {
-        :feed_attribute_id => feed_data[:name_id],
-        :field_id => PLACEHOLDER_FIELD_STRING
-      },
-      {
-        :feed_attribute_id => feed_data[:price_id],
-        :field_id => PLACEHOLDER_FIELD_PRICE
-      },
-      {
-        :feed_attribute_id => feed_data[:date_id],
-        :field_id => PLACEHOLDER_FIELD_DATE
-      }
-    ]
-  }
-
-  response = feed_mapping_srv.mutate([
-      {:operator => 'ADD', :operand => feed_mapping}
-  ])
-  if response and response[:value]
-    feed_mapping = response[:value].first
-    puts ('Feed mapping with ID %d and placeholder type %d was saved for feed' +
-        ' with ID %d.') % [
-          feed_mapping[:feed_mapping_id],
-          feed_mapping[:placeholder_type],
-          feed_mapping[:feed_id]
-        ]
-  else
-    raise new StandardError, 'No feed mappings were added.'
-  end
+  # Create a customizer feed. One feed per account can be used for all ads.
+  feed_data = create_customizer_feed(adwords, feed_name)
 
   # Now adding feed items -- the values we'd like to place.
+  now_date = Date.today()
+
   items_data = [
     {
       :name => 'Mars',
       :price => '$1234.56',
-      :date => '20140601 000000',
+      :date => now_date.strftime('%Y%m01 000000'),
       :ad_group_id => ad_group_ids[0]
     },
     {
       :name => 'Venus',
       :price => '$1450.00',
-      :date => '20140615 120000',
+      :date => now_date.strftime('%Y%m15 000000'),
       :ad_group_id => ad_group_ids[1]
      }
   ]
@@ -165,38 +96,6 @@ def add_ad_customizer(ad_group_ids)
     raise new StandardError, 'No feed items were added.'
   end
 
-  # Finally, creating a customer (account-level) feed with a matching function
-  # that determines when to use this feed. For this case we use the "IDENTITY"
-  # matching function that is always 'true' just to associate this feed with
-  # the customer. The targeting is done within the feed items using the
-  # :campaign_targeting, :ad_group_targeting, or :keyword_targeting attributes.
-  matching_function = {
-    :operator => 'IDENTITY',
-    :lhs_operand => [
-      {
-        :xsi_type => 'ConstantOperand',
-        :type => 'BOOLEAN',
-        :boolean_value => true
-      }
-    ]
-  }
-
-  customer_feed = {
-    :feed_id => feed_data[:feed_id],
-    :matching_function => matching_function,
-    :placeholder_types => [PLACEHOLDER_AD_CUSTOMIZER]
-  }
-
-  response = customer_feed_srv.mutate([
-      {:operator => 'ADD', :operand => customer_feed}
-  ])
-  if response and response[:value]
-    feed = response[:value].first
-    puts 'Customer feed with ID %d was added.' % [feed[:feed_id]]
-  else
-    raise new StandardError, 'No customer feeds were added.'
-  end
-
   # All set! We can now create ads with customizations.
   text_ad = {
     :xsi_type => 'TextAd',
@@ -214,7 +113,7 @@ def add_ad_customizer(ad_group_ids)
       :operator => 'ADD',
       :operand => {
         :ad_group_id => ad_group_id,
-        :ad => text_ad
+        :ad => text_ad.dup()
       }
     }
   end
@@ -231,25 +130,38 @@ def add_ad_customizer(ad_group_ids)
   end
 end
 
+def create_customizer_feed(adwords, feed_name)
+  ad_customizer_srv = adwords.service(:AdCustomizerFeedService, API_VERSION)
+  feed = {
+    :feed_name => feed_name,
+    :feed_attributes => [
+      {:name => 'Name', :type => 'STRING'},
+      {:name => 'Price', :type => 'PRICE'},
+      {:name => 'Date', :type => 'DATE_TIME'}
+    ]
+  }
+  operation = {:operand => feed, :operator => 'ADD'}
+  added_feed = ad_customizer_srv.mutate([operation])[:value].first()
+  puts "Created ad customizer feed with ID = %d and name = '%s'." %
+      [added_feed[:feed_id], added_feed[:feed_name]]
+  return {
+    :feed_id => added_feed[:feed_id],
+    :name_id => added_feed[:feed_attributes][0][:id],
+    :price_id => added_feed[:feed_attributes][1][:id],
+    :date_id => added_feed[:feed_attributes][2][:id]
+  }
+end
+
 if __FILE__ == $0
   API_VERSION = :v201502
 
-  # See the Placeholder reference page for a list of all the placeholder types
-  # and fields:
-  #     https://developers.google.com/adwords/api/docs/appendix/placeholders
-  PLACEHOLDER_AD_CUSTOMIZER = 10
-  PLACEHOLDER_FIELD_INTEGER = 1
-  PLACEHOLDER_FIELD_FLOAT = 2
-  PLACEHOLDER_FIELD_PRICE = 3
-  PLACEHOLDER_FIELD_DATE = 4
-  PLACEHOLDER_FIELD_STRING = 5
-
   begin
+    feed_name = 'INSERT_FEED_NAME_HERE'.to_s
     ad_group_ids = [
         'INSERT_AD_GROUP_ID_HERE'.to_i,
         'INSERT_AD_GROUP_ID_HERE'.to_i
     ]
-    add_ad_customizer(ad_group_ids)
+    add_ad_customizers(feed_name, ad_group_ids)
 
   # Authorization error.
   rescue AdsCommon::Errors::OAuth2VerificationRequired => e