V15: Update examples to add DMA consent field (#463)

examples/remarketing/add_customer_match_user_list.rb

@@ -32,7 +32,13 @@
 require 'date'
 require 'digest'
 
-def add_customer_match_user_list(customer_id, run_job, user_list_id, job_id)
+def add_customer_match_user_list(
+  customer_id,
+  run_job,
+  user_list_id,
+  job_id,
+  ad_user_data_consent,
+  ad_personalization_consent)
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
 
   if job_id.nil?
@@ -42,7 +48,7 @@ def add_customer_match_user_list(customer_id, run_job, user_list_id, job_id)
       list_name = client.path.user_list(customer_id, user_list_id)
     end
   end
-  add_users_to_customer_match_user_list(client, customer_id, run_job, list_name, job_id)
+  add_users_to_customer_match_user_list(client, customer_id, run_job, list_name, job_id, ad_user_data_consent, ad_personalization_consent)
 end
 
 # [START add_customer_match_user_list_3]
@@ -76,7 +82,7 @@ def create_customer_match_user_list(client, customer_id)
 # [END add_customer_match_user_list_3]
 
 # [START add_customer_match_user_list]
-def add_users_to_customer_match_user_list(client, customer_id, run_job, user_list, job_id)
+def add_users_to_customer_match_user_list(client, customer_id, run_job, user_list, job_id, ad_user_data_consent, ad_personalization_consent)
   offline_user_data_service = client.service.offline_user_data_job
 
   job_name = if job_id.nil?
@@ -86,6 +92,20 @@ def add_users_to_customer_match_user_list(client, customer_id, run_job, user_lis
       job.customer_match_user_list_metadata =
         client.resource.customer_match_user_list_metadata do |m|
           m.user_list = user_list
+
+          if !ad_user_data_consent.nil? || !ad_personalization_consent.nil?
+            m.consent = client.resource.consent do |c|
+              # Specifies whether user consent was obtained for the data you are
+              # uploading. For more details, see:
+              # https://www.google.com/about/company/user-consent-policy
+              unless ad_user_data_consent.nil?
+                c.ad_user_data = ad_user_data_consent
+              end
+              unless ad_personalization_consent.nil?
+                c.ad_personalization = ad_personalization_consent
+              end
+            end
+          end
         end
     end
 
@@ -341,6 +361,18 @@ def normalize_and_hash(str, trim_inner_spaces = false)
       options[:job_id] = v
     end
 
+    opts.on('-d', '--ad-user-data-consent [AD-USER-DATA_CONSENT]', String,
+        'The personalization consent status for ad user data for all members in the job.' \
+        'e.g. UNKNOWN, GRANTED, DENIED') do |v|
+      options[:ad_user_data_consent] = v
+    end
+
+    opts.on('-p', '--ad-personalization-consent [AD-PERSONALIZATION-CONSENT]', String,
+        'The personalization consent status for ad user data for all members in the job.' \
+        'e.g. UNKNOWN, GRANTED, DENIED') do |v|
+      options[:ad_personalization_consent] = v
+    end
+
     opts.separator ''
     opts.separator 'Help:'
 
@@ -356,6 +388,8 @@ def normalize_and_hash(str, trim_inner_spaces = false)
       options[:run_job],
       options[:user_list_id],
       options[:job_id],
+      options[:ad_user_data_consent],
+      options[:ad_personalization_consent],
     )
   rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
     e.failure.errors.each do |error|

examples/remarketing/upload_call_conversion.rb

@@ -32,7 +32,8 @@ def upload_call_conversion(
   conversion_date_time,
   conversion_value,
   conversion_custom_variable_id,
-  conversion_custom_variable_value)
+  conversion_custom_variable_value,
+  ad_user_data_consent)
   # GoogleAdsClient will read a config file from
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
@@ -53,15 +54,23 @@ def upload_call_conversion(
         cv.value = conversion_custom_variable_value
       end
     end
+
+    unless ad_user_data_consent.nil?
+      c.consent = client.resource.consent do |c|
+        # Specifies whether user consent was obtained for the data you are
+        # uploading. For more details, see:
+        # https://www.google.com/about/company/user-consent-policy
+        c.ad_user_data = ad_user_data_consent
+      end
+    end
   end
 
   # Issues a request to upload the call conversion.
   response = client.service.conversion_upload.upload_call_conversions(
     customer_id: customer_id,
-    # NOTE: This request contains a single conversion as a demonstration.
-    # However, if you have multiple conversions to upload, it's best to upload
-    # multiple conversions per request instead of sending a separate request per
-    # conversion. See the following for per-request limits:
+    # NOTE: This request only uploads a single conversion, but if you have
+    # multiple conversions to upload, it's most efficient to upload them in a
+    # single request. See the following for per-request limits for reference:
     # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
     conversions: [call_conversion],
     partial_failure: true
@@ -118,6 +127,7 @@ def upload_call_conversion(
   # associate with the call conversion upload.
   options[:conversion_custom_variable_id] = nil;
   options[:conversion_custom_variable_value] = nil;
+  options[:ad_user_data_consent] = nil;
 
   OptionParser.new do |opts|
     opts.banner = sprintf('Usage: %s [options]', File.basename(__FILE__))
@@ -149,18 +159,24 @@ def upload_call_conversion(
       options[:conversion_value] = v.to_f
     end
 
-    opts.on('-d', '--conversion-custom-variable-id CONVERSION-CUSTOM-VARIABLE-ID', \
+    opts.on('-w', '--conversion-custom-variable-id CONVERSION-CUSTOM-VARIABLE-ID', \
             String, '(Optional) The ID of the conversion custom variable to ' \
             'associate with the upload') do |v|
       options[:conversion_custom_variable_id] = v
     end
 
-    opts.on('-u', '--conversion-custom-variable-value CONVERSION-CUSTOM-VARIABLE-VALUE', \
+    opts.on('-x', '--conversion-custom-variable-value CONVERSION-CUSTOM-VARIABLE-VALUE', \
             String, '(Optional) The value of the conversion custom ' \
             'variable to associate with the upload') do |v|
       options[:conversion_custom_variable_value] = v
     end
 
+    opts.on('-d', '--ad-user-data-consent AD-USER-DATA_CONSENT', \
+            String, '(Optional) The data consent status for ad user data for all members in the job.' \
+            'e.g. UNKNOWN, GRANTED, DENIED') do |v|
+      options[:ad_user_data_consent] = v
+    end
+
     opts.separator ''
     opts.separator 'Help:'
 
@@ -180,6 +196,7 @@ def upload_call_conversion(
       options.fetch(:conversion_value),
       options[:conversion_custom_variable_id],
       options[:conversion_custom_variable_value],
+      options[:ad_user_data_consent],
     )
   rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
     e.failure.errors.each do |error|

examples/remarketing/upload_enhanced_conversions_for_leads.rb

@@ -92,9 +92,9 @@ def upload_conversion_with_identifiers(
     # uploading. For more details, see:
     # https://www.google.com/about/company/user-consent-policy
     unless raw_record["ad_user_data_consent"].nil?
-      # cc.consent.ad_user_data = client.enums.ConsentStatusEnum[
-      #   raw_record["ad_user_data_consent"]
-      # ]
+      cc.consent = client.resource.consent do |c|
+        c.ad_user_data = ad_user_data_consent
+      end
     end
     # [END add_conversion_details]
 
@@ -117,6 +117,7 @@ def upload_conversion_with_identifiers(
   end
   # [END add_user_identifiers]
 
+  # [START upload_conversion]
   response = client.service.conversion_upload.upload_click_conversions(
     customer_id: customer_id,
     conversions: [click_conversion],
@@ -131,6 +132,7 @@ def upload_conversion_with_identifiers(
     puts "Uploaded click conversion that happened at #{result.conversion_date_time} " \
       "to #{result.conversion_action}."
   end
+  # [END upload_conversion]
 end
 
 # [START normalize_and_hash]
@@ -173,8 +175,8 @@ def normalize_and_hash_email(email)
   options[:conversion_date_time] = 'INSERT_CONVERSION_DATE_TIME_HERE'
   options[:conversion_value] = 'INSERT_CONVERSION_VALUE_HERE'
   options[:order_id] = nil
-  options[:gclid] = 'INSERT_GCLID_HERE'
-  options[:ad_user_data_consent] = 'INSERT_AD_USER_DATA_CONSENT_ENUM_HERE'
+  options[:gclid] = nil
+  options[:ad_user_data_consent] = nil
 
   OptionParser.new do |opts|
     opts.banner = sprintf('Usage: %s [options]', File.basename(__FILE__))
@@ -211,7 +213,8 @@ def normalize_and_hash_email(email)
 
     opts.on('-d', '--ad-user-data-dconsent GCLID', String,
             'The data consent status for ad user data for all members in' \
-            'the job.') do |v|
+            'the job.' \
+            'e.g. UNKNOWN, GRANTED, DENIED') do |v|
       options[:ad_user_data_consent] = v
     end
 

examples/remarketing/upload_store_sales_transactions.rb

@@ -39,7 +39,9 @@ def upload_store_sales_transactions(
   merchant_center_account_id,
   region_code,
   language_code,
-  quantity)
+  quantity,
+  ad_user_data_consent,
+  ad_personalization_consent)
   # GoogleAdsClient will read a config file from
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
@@ -66,6 +68,8 @@ def upload_store_sales_transactions(
     offline_user_data_job_resource_name,
     conversion_action_id,
     custom_value,
+    ad_user_data_consent,
+    ad_personalization_consent
   )
 
   # Issues an asynchronous request to run the offline user data job.
@@ -181,10 +185,13 @@ def add_transactions_to_offline_user_data_job(
   customer_id,
   offline_user_data_job_resource_name,
   conversion_action_id,
-  custom_value)
+  custom_value,
+  ad_user_data_consent,
+  ad_personalization_consent)
   # Constructs the operation for each transaction.
   user_data_job_operations = build_offline_user_data_job_operations(
-    client, customer_id, conversion_action_id, custom_value)
+    client, customer_id, conversion_action_id, custom_value, ad_user_data_consent,
+    ad_personalization_consent)
 
   # [START enable_warnings_1]
   # Issues a request to add the operations to the offline user data job.
@@ -238,22 +245,24 @@ def build_offline_user_data_job_operations(
   client,
   customer_id,
   conversion_action_id,
-  custom_value)
+  custom_value,
+  ad_user_data_consent,
+  ad_personalization_consent)
   operations = []
 
   # Creates the first transaction for upload based on an email address
   # and state.
-  operations << client.operation.create_resource.offline_user_data_job do |job|
-    job.user_identifiers << client.resource.user_identifier do |id|
+  operations << client.operation.create_resource.offline_user_data_job do |op|
+    op.user_identifiers << client.resource.user_identifier do |id|
       # Email addresses must be normalized and hashed.
       id.hashed_email = normalize_and_hash("[email protected]")
     end
-    job.user_identifiers << client.resource.user_identifier do |id|
+    op.user_identifiers << client.resource.user_identifier do |id|
       id.address_info = client.resource.offline_user_address_info do |info|
         info.state = "NY"
       end
     end
-    job.transaction_attribute = client.resource.transaction_attribute do |t|
+    op.transaction_attribute = client.resource.transaction_attribute do |t|
       t.conversion_action = client.path.conversion_action(
         customer_id, conversion_action_id)
       t.currency_code = "USD"
@@ -267,11 +276,24 @@ def build_offline_user_data_job_operations(
       t.transaction_date_time = "2020-05-01 23:52:12"
       t.custom_value = custom_value unless custom_value.nil?
     end
+    if !ad_user_data_consent.nil? || !ad_personalization_consent.nil?
+      op.consent = client.resource.consent do |c|
+        # Specifies whether user consent was obtained for the data you are
+        # uploading. For more details, see:
+        # https://www.google.com/about/company/user-consent-policy
+        unless ad_user_data_consent.nil?
+          c.ad_user_data = ad_user_data_consent
+        end
+        unless ad_personalization_consent.nil?
+          c.ad_personalization = ad_personalization_consent
+        end
+      end
+    end
   end
 
   # Creates the second transaction for upload based on a physical address.
-  operations << client.operation.create_resource.offline_user_data_job do |job|
-    job.user_identifiers << client.resource.user_identifier do |id|
+  operations << client.operation.create_resource.offline_user_data_job do |op|
+    op.user_identifiers << client.resource.user_identifier do |id|
       id.address_info = client.resource.offline_user_address_info do |info|
         # First and last name must be normalized and hashed.
         info.hashed_first_name = normalize_and_hash("Dana")
@@ -281,7 +303,7 @@ def build_offline_user_data_job_operations(
         info.postal_code = "10011"
       end
     end
-    job.transaction_attribute = client.resource.transaction_attribute do |t|
+    op.transaction_attribute = client.resource.transaction_attribute do |t|
       t.conversion_action = client.path.conversion_action(
         customer_id, conversion_action_id)
       t.currency_code = "EUR"
@@ -466,6 +488,18 @@ def check_job_status(
       options[:quantity] = v
     end
 
+    opts.on('-d', '--ad-user-data-consent [AD-USER-DATA_CONSENT]', String,
+        'The personalization consent status for ad user data for all members in the job.' \
+        'e.g. UNKNOWN, GRANTED, DENIED') do |v|
+      options[:ad_user_data_consent] = v
+    end
+
+    opts.on('-p', '--ad-personalization-consent [AD-PERSONALIZATION-CONSENT]', String,
+        'The personalization consent status for ad user data for all members in the job.' \
+        'e.g. UNKNOWN, GRANTED, DENIED') do |v|
+      options[:ad_personalization_consent] = v
+    end
+
     opts.separator ''
     opts.separator 'Help:'
 
@@ -491,6 +525,8 @@ def check_job_status(
       options[:region_code],
       options[:language_code],
       options[:quantity],
+      options[:ad_user_data_consent],
+      options[:ad_personalization_consent],
     )
   rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
     e.failure.errors.each do |error|