Add incentives examples

[dorasun]

Change-Id: I57fa8a776fb8a1cbd43f6c1d3a1a71c3c63bdd19

[bobhancockg]

Code Vetting & Review Recommendations

Overall, the implementation for adding incentive examples (apply_incentive.rb and fetch_incentive.rb) is well-structured. Below are recommended improvements to align with google-ads-ruby repository standards, fix documentation indexing tags, ensure type safety, and standardize monetary formatting.

---

1. examples/incentives/apply_incentive.rb

• Default Parameter Value: Add country_code = nil to the method signature so calling apply_incentive(customer_id, incentive_id) programmatically works without explicitly passing nil:

  def apply_incentive(customer_id, incentive_id, country_code = nil)

• Type Safety for selected_incentive_id: Explicitly call .to_i on incentive_id when constructing request_args for protobuf field type safety (int64):

  request_args = {
    customer_id: customer_id,
    selected_incentive_id: incentive_id.to_i
  }

• CLI Default Initializers & Validation: Initialize options[:incentive_id] = 'INSERT_INCENTIVE_ID_HERE' at the top of if __FILE__ == $0 to match the doc comments, and update argument validation accordingly:

  options[:customer_id] = 'INSERT_CUSTOMER_ID_HERE'
  options[:incentive_id] = 'INSERT_INCENTIVE_ID_HERE'

  if options[:customer_id].nil? ||
      options[:customer_id] == 'INSERT_CUSTOMER_ID_HERE' ||
      options[:incentive_id].nil? ||
      options[:incentive_id] == 'INSERT_INCENTIVE_ID_HERE'
    puts 'Missing required arguments. See usage:'
    puts 'Customer ID and Incentive ID are required.'
    exit 1
  end

---

2. examples/incentives/fetch_incentive.rb

• Documentation Region Tags: Add # [START fetch_incentive] and # [END fetch_incentive] region tags around the main method so Google Developers documentation (devsite) can automatically index the code snippet.
• Standardize Currency Formatting in format_money: Simplify calculation to cleanly format zero, fractional, and negative currency values with standard 2 decimal places:

  def format_money(money)
    return 'N/A' if money.nil?
  
    amount = money.units.to_f + (money.nanos.to_f / 1_000_000_000.0)
    sprintf('%.2f %s', amount, money.currency_code)
  end

• CLI Option Placeholder & Check: Initialize options[:email] = 'INSERT_EMAIL_HERE' and validate against INSERT_EMAIL_HERE in if __FILE__ == $0.

[bobhancockg]

Overall, the implementation for adding incentive examples is well-structured and incorporates previous feedback nicely. Here are a few remaining recommendations and optimizations before merging:

1. examples/incentives/apply_incentive.rb:

   • Clean up redundant request_args[:country_code] = country_code if country_code duplicate assignment on line 36.

2. examples/incentives/fetch_incentive.rb:

   • Update request field name from type: :ACQUISITION to incentive_type: :ACQUISITION to match current Google Ads API protobuf definitions (v24+) and avoid runtime ArgumentError.
   • Provide default nil arguments in def fetch_incentive(email, language_code = nil, country_code = nil) and construct request args using .compact.
   • Fix missing whitespace in string continuation on lines 51-52 ("type." \ "Non-CYO" -> "type.Non-CYO").
   • Defensively format monetary currency strings against empty protobuf defaults ("").

[bobhancockg]

Updated the PR with the following optimizations:

• Parameter Defaults & API Alignment:
  • : Defaulted country_code to 'US' (required by API proto schema) rather than nil to avoid INVALID_ARGUMENT when omitted.
  • : Provided default values (language_code = 'en', country_code = 'US') matching API proto defaults.
• Defensive Protobuf Traversal:
  • Used incentive_id&.to_i to prevent coercing nil to 0.
  • Added safe navigation (response.incentive_offer&.cyo_incentives).
  • Added !field.to_s.empty? checks for protobuf strings before output.
  • Improved requirement fallback message when spend requirement is absent.
  • Cleaned up format_money currency formatting.
• Documentation / Code Snippet Tags:
  • Extended [START fetch_incentive] / [END fetch_incentive] scope to encompass helper functions (print_incentive_details, format_requirement, format_money) so extracted DevSite snippets are complete and runnable.
• Diagnostics & Error Reporting:
  • Surfaced e.request_id in stderr when catching GoogleAdsError across both scripts.
  • Standardized CLI parameter validation to report the exact missing flag with OptionParser usage banner.

[bobhancockg]

Style / Formatting: Trailing whitespace on line 36 after .compact.

[bobhancockg]

Enhancement (API Coverage): The IncentiveOffer message can also contain consolidated_terms_and_conditions_url (combining terms across all CYO incentive offers). Consider printing it when present:

  if !response.incentive_offer.consolidated_terms_and_conditions_url.to_s.empty?
    puts "Consolidated terms and conditions: '#{response.incentive_offer.consolidated_terms_and_conditions_url}'"
  end

[bobhancockg]

Defensive validation: Consider checking options[:email].to_s.empty? instead of just options[:email].nil? (consistent with --country-code in apply_incentive.rb line 114):

  if options[:email].to_s.empty? || options[:email] == 'INSERT_EMAIL_HERE'
    puts "Missing required argument: --email (-E) is required.\n\n"
    puts parser
    exit 1
  end

This defensively catches empty string inputs (e.g. -E "").

[bobhancockg]

UX / Output: If the API returns a response where both creation_time and coupon_code happen to be empty, the method currently completes silently with no output. Consider adding a fallback confirmation if neither is printed:

  if !response.creation_time.to_s.empty?
    puts "Incentive was created at '#{response.creation_time}'."
  end
  if !response.coupon_code.to_s.empty?
    puts "Applied incentive with coupon code '#{response.coupon_code}'."
  end
  if response.creation_time.to_s.empty? && response.coupon_code.to_s.empty?
    puts "Incentive applied successfully."
  end