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]

country_code is already included in the hash literal and cleaned by .compact. Line 36 is a leftover duplicate assignment from commit 2 and can be removed.

Suggested change

	# Issues the request.
	request_args = {
	customer_id: customer_id.to_s.tr('-', ''),
	selected_incentive_id: incentive_id.to_i,
	country_code: country_code
	# Issues the request.
	request_args = {
	customer_id: customer_id.to_s.tr('-', ''),
	selected_incentive_id: incentive_id.to_i,
	country_code: country_code
	}.compact

[bobhancockg]

1. In FetchIncentiveRequest (v24+ / v25+), the field name is incentive_type rather than type. Passing type: will trigger an ArgumentError: Unknown field name :type on current protobuf stubs.
2. Adding default nil values (language_code = nil, country_code = nil) and building request_args with .compact allows callers to invoke fetch_incentive(email) programmatically while relying on the API defaults (en, US).

Suggested change

	def fetch_incentive(email, language_code, country_code)
	# GoogleAdsClient will read a config file from a default location
	# if no path is passed.
	client = Google::Ads::GoogleAds::GoogleAdsClient.new
	# Issues the request.
	response = client.service.incentive.fetch_incentive(
	email: email,
	language_code: language_code,
	country_code: country_code,
	# Passing :ACQUISITION as the symbol representation of the IncentiveType enum.
	type: :ACQUISITION
	)
	def fetch_incentive(email, language_code = nil, country_code = nil)
	# GoogleAdsClient will read a config file from a default location
	# if no path is passed.
	client = Google::Ads::GoogleAds::GoogleAdsClient.new
	# Issues the request.
	request_args = {
	email: email,
	language_code: language_code,
	country_code: country_code,
	# Passing :ACQUISITION as the symbol representation of the IncentiveType enum.
	incentive_type: :ACQUISITION
	}.compact
	response = client.service.incentive.fetch_incentive(request_args)

[bobhancockg]

1. Line continuation without whitespace causes "type." \ "Non-CYO" to concatenate into "type.Non-CYO". Adding a space after the period fixes the output.
2. Adding .compact defensively prevents iterating over any unset offer slots.

Suggested change

	if response.incentive_offer.cyo_incentives
	cyo = response.incentive_offer.cyo_incentives
	[cyo.low_offer, cyo.medium_offer, cyo.high_offer].each do |incentive|
	print_incentive_details(incentive)
	end
	else
	puts "Incentive offer is not a CHOOSE_YOUR_OWN_INCENTIVE type." \
	"Non-CYO offers are not supported by this example."
	end
	if response.incentive_offer.cyo_incentives
	cyo = response.incentive_offer.cyo_incentives
	[cyo.low_offer, cyo.medium_offer, cyo.high_offer].compact.each do |incentive|
	print_incentive_details(incentive)
	end
	else
	puts "Incentive offer is not a CHOOSE_YOUR_OWN_INCENTIVE type. " \
	"Non-CYO offers are not supported by this example."
	end

[bobhancockg]

In protobuf messages, unset string fields default to "" (empty string), which is truthy in Ruby and bypasses || 'N/A', producing strings like "100.00 ". Checking .to_s.empty? ensures unset strings properly fallback to 'N/A'.

Suggested change

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