Support for Google Ads API v16. (#483)

Change-Id: Id477c2b68a41685db17748533b09102a55c3f5c9

CHANGELOG.md

@@ -1,3 +1,7 @@
+27.0.0
+------
+ - Compatibility with v16 of the API: https://developers.google.com/google-ads/api/docs/release-notes
+
 26.0.0
 ------
  - Removed support for v13.

examples/account_management/verify_advertiser_identity.rb

@@ -0,0 +1,131 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright 2024 Google LLC
+#
+# 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
+#
+#     https://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 illustrates how to retrieve the status of the advertiser
+# identity verification program and, if required and not already started, how
+# to start the verification process.
+
+require 'optparse'
+require 'date'
+require 'google/ads/google_ads'
+
+def verify_advertiser_identity(customer_id)
+  # GoogleAdsClient will read a config file from
+  # ENV['HOME']/google_ads_config.rb when called without parameters
+  client = Google::Ads::GoogleAds::GoogleAdsClient.new
+
+  client.configure do |config|
+    config.login_customer_id = customer_id
+  end
+
+  identity_verification = get_identity_verification(client, customer_id)
+
+  if identity_verification.nil?
+    puts "Account #{customer_id} is not required to perform mandatory identity verification."
+    puts "See https://support.google.com/adspolicy/answer/9703665 for details on how " \
+      "and when an account is required to undergo the advertiser identity " \
+      "verification program."
+  else
+    if identity_verification.verification_progress.action_url.nil?
+      start_identity_verification(client, customer_id)
+
+      # Call GetIdentityVerification again to retrieve the verification
+      # progress after starting an identity verification session.
+      get_identity_verification(client, customer_id)
+    else
+      # If there is an identity verification session in progress, there is no
+      # need to start another one by calling start_identity_verification.
+      puts "There is an advertiser identity verification session in progress."
+
+      progress = identity_verification.verification_progress
+      puts "The URL for the verification process is #{progress.action_url} and " \
+        "it will expire at #{progress.invitation_link_expiration_time}."
+    end
+  end
+end
+
+# [START verify_advertiser_identity_1]
+def get_identity_verification(client, customer_id)
+  response = client.service.identity_verification.get_identity_verification(
+    customer_id: customer_id
+  )
+
+  return nil if response.nil? || response.identity_verification.empty?
+
+  identity_verification = response.identity_verification.first
+  deadline = identity_verification.
+    identity_verification_requirement.
+    verification_completion_deadline_time
+  progress = identity_verification.verification_progress
+  puts "Account #{customer_id} has a verification completion deadline " \
+    "of #{deadline} and status #{progress.program_status} for advertiser " \
+    "identity verification."
+
+  identity_verification
+end
+# [END verify_advertiser_identity_1]
+
+# [START verify_advertiser_identity_2]
+def start_identity_verification(client, customer_id)
+  client.service.identity_verification.start_identity_verification(
+    customer_id: customer_id,
+    verification_program: :ADVERTISER_IDENTITY_VERIFICATION,
+  )
+end
+# [END verify_advertiser_identity_2]
+
+if __FILE__ == $PROGRAM_NAME
+  # Running the example with -h will print the command line usage.
+  options = {}
+
+  OptionParser.new do |opts|
+    opts.banner = sprintf('Usage: ruby %s [options]', File.basename(__FILE__))
+
+    opts.separator ''
+    opts.separator 'Options:'
+
+    opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
+      options[:customer_id] = v
+    end
+
+    opts.separator ''
+    opts.separator 'Help:'
+
+    opts.on_tail('-h', '--help', 'Show this message') do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  begin
+    verify_advertiser_identity(options.fetch(:customer_id).tr("-", ""))
+  rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
+    e.failure.errors.each do |error|
+      STDERR.printf("Error with message: %s\n", error.message)
+      if error.location
+        error.location.field_path_elements.each do |field_path_element|
+          STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
+        end
+      end
+      error.error_code.to_h.each do |k, v|
+        next if v == :UNSPECIFIED
+        STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
+      end
+    end
+    raise
+  end
+end

examples/advanced_operations/get_ad_group_bid_modifiers.rb

@@ -58,15 +58,16 @@ def get_ad_group_bid_modifiers(customer_id, ad_group_id = nil)
     ad_group_bid_modifier = row.ad_group_bid_modifier
     ad_group = row.ad_group
     campaign = row.campaign
-    bid_modifier = '"nil"'
 
-    if ad_group_bid_modifier.bid_modifier
-      bid_modifier = sprintf("%.2f", ad_group_bid_modifier.bid_modifier)
+    print "Ad group bid modifier with criterion ID #{ad_group_bid_modifier.criterion_id} in " \
+      "ad group ID #{ad_group.id} of campaign ID #{campaign.id} "
+
+    if ad_group_bid_modifier.has_bid_modifier?
+      puts "has a bid modifier value of #{sprintf("%.2f", ad_group_bid_modifier.bid_modifier)}."
+    else
+      puts "does NOT have a bid modifier value."
     end
 
-    puts "Ad group bid modifier with criterion ID #{ad_group_bid_modifier.criterion_id}, bid " \
-        "modifier value #{bid_modifier} was found in an ad group with ID #{ad_group.id} of " \
-        "campaign ID #{campaign.id}."
 
     criterion_details = "  - Criterion type: #{ad_group_bid_modifier.criterion}, "
 

examples/extensions/add_call.rb → examples/assets/add_call.rb

@@ -15,7 +15,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# This example adds a call extension to a specific account.
+# This example adds a call asset to a specific account.
 
 require 'date'
 require 'google/ads/google_ads'
@@ -29,15 +29,15 @@ def add_call(customer_id,
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
 
-  asset_resource_name = add_extension_asset(client,
+  asset_resource_name = add_call_asset(client,
     customer_id,
     phone_number,
     phone_country,
     conversion_action_id)
   link_asset_to_account(client, customer_id, asset_resource_name)
 end
 
-def add_extension_asset(client,
+def add_call_asset(client,
     customer_id,
     phone_number,
     phone_country,

examples/extensions/add_hotel_callout.rb → examples/assets/add_hotel_callout.rb

@@ -15,7 +15,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# This example adds a hotel callout extension to a specific account.
+# This example adds a hotel callout asset to a specific account.
 
 require 'optparse'
 require 'google/ads/google_ads'
@@ -26,16 +26,16 @@ def add_hotel_callout(customer_id, language_code)
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
 
-  # Creates an extension feed item as hotel callout.
-  asset_resource_names = add_assets(client, customer_id, language_code)
+  # Creates a hotel callout asset.
+  asset_resource_names = add_hotel_callout_assets(client, customer_id, language_code)
 
-  # Adds the extension feed item to the account.
+  # Adds the asset at the account level, so it will serve in all eligible campaigns.
   link_assets_to_account(client, customer_id, asset_resource_names)
 
 end
 
-# Creates a new extension feed item for the callout extension.
-def add_assets(client, customer_id, language_code)
+# Creates a new asset.
+def add_hotel_callout_assets(client, customer_id, language_code)
   operations = [
     client.resource.hotel_callout_asset do |hca|
       hca.text = 'Activities'
@@ -62,7 +62,7 @@ def add_assets(client, customer_id, language_code)
   end
 end
 
-# Adds the extension feed item to the customer account.
+# Adds the asset to the customer account.
 def link_assets_to_account(client, customer_id, asset_resource_names)
   operations = asset_resource_names.map do |asset_resource_name|
     client.operation.create_resource.customer_asset do |ca|

examples/extensions/add_lead_form_extension.rb → examples/assets/add_lead_form_asset.rb

@@ -15,15 +15,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# Creates a lead form and a lead form extension for a campaign.
+# Creates a lead form and a lead form asset for a campaign.
 #
 # Run add_campaigns.rb to create a campaign.
 
 require 'optparse'
 require 'google/ads/google_ads'
 require 'date'
 
-def add_lead_form_extension(customer_id, campaign_id)
+def add_lead_form_asset(customer_id, campaign_id)
   # GoogleAdsClient will read a config file from
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
@@ -33,15 +33,15 @@ def add_lead_form_extension(customer_id, campaign_id)
     customer_id,
   )
 
-  create_lead_form_extension(
+  create_lead_form_campaign_asset(
     client,
     customer_id,
     campaign_id,
     lead_form_asset,
   )
 end
 
-# [START add_lead_form_extension]
+# [START add_lead_form_asset]
 def create_lead_form_asset(client, customer_id)
   operation = client.operation.create_resource.asset do |a|
     a.name = "Interplanetary Cruise #{(Time.new.to_f * 1000).to_i} Lead Form"
@@ -107,10 +107,10 @@ def create_lead_form_asset(client, customer_id)
   puts "Asset with resource name #{asset_name} was created."
   asset_name
 end
-# [END add_lead_form_extension]
+# [END add_lead_form_asset]
 
-# [START add_lead_form_extension_1]
-def create_lead_form_extension(client, customer_id, campaign_id, lead_form_asset)
+# [START add_lead_form_asset_1]
+def create_lead_form_campaign_asset(client, customer_id, campaign_id, lead_form_asset)
   operation = client.operation.create_resource.campaign_asset do |ca|
     ca.asset = lead_form_asset
     ca.field_type = :LEAD_FORM
@@ -125,7 +125,7 @@ def create_lead_form_extension(client, customer_id, campaign_id, lead_form_asset
   puts "Created campaign asset #{response.results.first.resource_name} for " \
     "campaign #{campaign_id}."
 end
-# [END add_lead_form_extension_1]
+# [END add_lead_form_asset_1]
 
 if __FILE__ == $0
   options = {}
@@ -164,7 +164,7 @@ def create_lead_form_extension(client, customer_id, campaign_id, lead_form_asset
   end.parse!
 
   begin
-    add_lead_form_extension(
+    add_lead_form_asset(
       options.fetch(:customer_id).tr("-", ""),
       options.fetch(:campaign_id),
     )

examples/extensions/add_prices.rb → examples/assets/add_prices.rb

@@ -15,7 +15,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# Adds a price extension and associates it with an account.
+# Adds a price asset and associates it with an account.
 
 require 'optparse'
 require 'google/ads/google_ads'
@@ -34,8 +34,6 @@ def add_prices(customer_id)
 end
 
 def create_price_asset(client, customer_id)
-  # The operation creates a customer extension setting with price feed item.
-  # This associates the price extension to your account.
   operation = client.operation.create_resource.asset do |asset|
     asset.name = "Price Asset ##{(Time.new.to_f * 1000).to_i}"
     asset.tracking_url_template = 'http://tracker.example.com/?u={lpurl}'
@@ -45,7 +43,7 @@ def create_price_asset(client, customer_id)
       price.price_qualifier = :FROM
       price.language_code = 'en'
 
-      # To create a price extension, at least three price offerings are needed.
+      # To create a price asset, at least three price offerings are needed.
       price.price_offerings << create_price_offer(
           client, 'Scrubs', 'Body Scrub, Salt Scrub', 60_000_000, # 60 USD
           'USD', :PER_HOUR, 'http://www.example.com/scrubs',
@@ -67,7 +65,7 @@ def create_price_asset(client, customer_id)
   )
 
   resource_name = response.results.first.resource_name
-  puts "Created extension feed with resource name '#{resource_name}'"
+  puts "Created asset with resource name '#{resource_name}'"
 
   resource_name
 end

examples/extensions/add_sitelinks_using_assets.rb → examples/assets/add_sitelinks.rb

@@ -21,7 +21,7 @@
 require 'google/ads/google_ads'
 require 'date'
 
-def add_sitelinks_using_assets(customer_id, campaign_id)
+def add_sitelinks(customer_id, campaign_id)
   # GoogleAdsClient will read a config file from
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
@@ -133,7 +133,7 @@ def link_sitelinks_to_campaign(client, resource_names, customer_id, campaign_id)
   end.parse!
 
   begin
-    add_sitelinks_using_assets(options.fetch(:customer_id).tr("-", ""), options.fetch(:campaign_id))
+    add_sitelinks(options.fetch(:customer_id).tr("-", ""), options.fetch(:campaign_id))
   rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
     e.failure.errors.each do |error|
       STDERR.printf("Error with message: %s\n", error.message)