概览

要集成优惠的合作伙伴必须在集成之前先完成基于商家或实体（小规模测试）的集成步骤。本指南将详细介绍优惠集成的实现、测试和启动。在完成集成步骤之前，请先通读本概览和优惠政策。

优惠

您可以通过优惠集成传达与适用于特定时间和服务的商家促销活动和折扣相关的结构化信息。优惠由实际优惠（折扣百分比、优惠金额等）、有效期（特定时间、一周中的某几天等）和适用用途（该优惠仅适用于特定服务）以及复杂的限制组合组成。

优惠示例：

  • 12 月周三和周四中午 12:00 至下午 5:00 可享开胃菜半价优惠
  • 母亲节当天下午 6:00 至晚上 10:00，餐后甜点买一送一
  • 每周日上午 10:00 至下午 2:00 可享早午餐主菜立减 5 元
  • 10% 的到店优惠，可与 5% 的高级订阅者优惠和 5% 的用户通过您的应用付款优惠叠加使用。

要成为集成的一部分，优惠信息必须符合技术数据模型并满足我们的资格要求。请务必查看我们的优惠信息政策，确保您的集成符合相关规定，并了解有关如何处理不符合技术要求的优惠的说明。

对优惠信息的实现

优惠信息的集成由需每天上传或以确保高准确度（即减少过时）的频率上传的 2 个 Feed 组成：

OfferFeed

字段名称类型要求说明
data对象数组
(Offer)

优惠

字段名称类型要求说明
offer_id字符串

必需

相应优惠的唯一 ID。 必需。
entity_ids字符串数组

参与相应优惠的商家列表。
add_on_offer_applicable_to_all_entities布尔值

如果为 true，则表示相应优惠适用于聚合器下的所有实体。 仅适用于加购优惠。
offer_source枚举
(OfferSource)

必需

优惠可以由集合商家、单个商家甚至第三方作为附加服务提供。 必需。
action_type枚举
(ActionType)

必需

提供优惠的服务。一个 offer_id 只能属于一个 action_type。如果某优惠可用于多种服务类型，则应为每种服务类型创建具有唯一 ID 的重复优惠。 必需。
offer_modes枚举
(OfferMode)的数组

必需

可享受优惠的方式 - 预约、在线等。必需属性。
offer_category枚举
(OfferCategory)

必需

优惠的类别。 必需。
source_assigned_priority数值

非负整数（[1-100]，其中 1 表示最高优先级），用于指示来源分配的优惠优先级。如果同一商家有多项优惠，此属性将作为对优惠进行排名的信号。0 表示未设置优先级。
offer_details对象
(OfferDetails)

必需

优惠的详细信息，例如折扣、预订费用等。必需。
offer_restrictions对象
(OfferRestrictions)

必需

说明优惠的限制条件，例如是否需要订阅/付款方式、此优惠是否可以与其他优惠（以及哪些类型的优惠）叠加使用等。必需属性。
coupon对象
(Coupon)

优惠券的详细信息。 对于 offer_category：OFFER_CATEGORY_ADD_ON_COUPON_OFFER，此属性为必需属性。
payment_instrument对象
(PaymentInstrument)

支付方式的详细信息。 对于 offer_category：OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER，此属性为必需属性。
subscription对象
(Subscription)

订阅的详细信息。 对于 offer_category：OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER，此属性为必需属性。
terms对象
(Terms)

必需

优惠的条款及条件。 必需。
validity_periods对象数组
(ValidityPeriod)

必需

优惠的有效期。描述了优惠的有效时间段，包括开始时间和结束时间、星期几等。必需属性。
offer_url字符串

商家的优惠页面网址。 对于 offer_category：OFFER_CATEGORY_BASE_OFFER，此属性为必需属性。
image_url字符串

指向商家优惠图片的网址。

OfferDetails

字段名称类型要求说明
offer_display_text字符串

必需

优惠提供商希望在搜索结果页上向客户展示的优惠文字。 必需。
oneOf
(offer_specification)

必需

此 oneOf 中的字段只能设置一个。
max_discount_value对象
(Money)

可享受的最大折扣。例如，九折优惠，最高可省 100 美元。
min_spend_value对象
(Money)

享受折扣所需的最低支出金额。 例如，总价达到 100 美元或以上时，可享受 10% 的折扣。
booking_cost对象
(Money)

预订相应优惠的费用。例如，预订价格为 15 美元的餐桌可享受 100 美元的最终账单折扣。
booking_cost_unit枚举
(FeeUnit)

预订费用的单位。例如，按人、按交易。
convenience_fee对象
(Fee)

booking_cost_adjustable布尔值

预订费用是否可调整，即预订费用是否从最终账单中扣除。 例如：预订晚餐可享七折优惠。预订费用为 15 美元，将用于抵扣最终账单。 因此，最终账单：总支出 - 30% - 15 美元
additional_fees对象数组
(AdditionalFee)

向用户收取的额外费用。 例如：便利性、处理等。

Money

表示含有货币类型的金额。

字段名称类型要求说明
currency_code字符串

ISO 4217 中定义的由 3 个字母组成的货币代码。
units字符串

金额的整数单位。 例如，如果 currencyCode 是 "USD"，则 1 单位就是一美元。
nanos数值

金额的纳诺 (10^-9) 单位数。 这个值必须在 -999,999,999（含）至 +999,999,999（含）之间。 如果 units 是正数，nanos 必须是正数或零。 如果 units 是零，nanos 可以是正数、零或负数。 如果 units 是负数，nanos 必须是负数或零。 例如，$-1.75 表示为 units=-1 和 nanos=-750000000。

费用

字段名称类型要求说明
unit枚举
(FeeUnit)

type枚举
(FeeType)

oneOf
(cost)

此 oneOf 中的字段只能设置一个。

MoneyRange

字段名称类型要求说明
min_amount对象
(Money)

max_amount对象
(Money)

AdditionalFee

字段名称类型要求说明
name字符串

必需

附加费用的名称。示例：手续费、处理费等。 必需属性。
fee对象
(Fee)

OfferRestrictions

字段名称类型要求说明
combinable_with_other_offers布尔值

相应优惠是否可与其他优惠同时使用。 如果为 true，合作伙伴可以指定相应优惠可与哪些优惠组合使用。如果同时设置了 combinable_offer_categories 和 combinable_offer_ids，则任何满足上述任一条件的优惠都可组合。
combinable_offer_categories枚举
(OfferCategory)的数组

相应优惠可与其他优惠叠加使用的优惠类型列表。例如，此优惠可能可以与其他优惠券叠加使用。如果 combinable_with_other_offers 为 true，且此字段未设置，则所有类型都可组合。
combinable_offer_ids字符串数组

相应优惠可与哪些 offer_id 对应的优惠同时使用。某些优惠可能只能与某些特定的其他 offer_id（可视为父优惠）叠加使用。如果 combinable_with_other_offers 为 true 且此字段未设置，则所有优惠 ID 均可组合。
inclusions对象数组
(OfferCondition)

优惠生效必须满足的条件列表（例如，不含酒精的饮料、食物）。
exclusions对象数组
(OfferCondition)

会使优惠失效的条件列表（例如，自助餐、套餐优惠和鸡尾酒）。
min_guest数值

享受相应优惠所需的最少人数。
food_offer_restrictions对象
(FoodOfferRestrictions)

特定于食品优惠的限制。

OfferCondition

字段名称类型要求说明
description字符串

FoodOfferRestrictions

字段名称类型要求说明
meal_types枚举
(MealType)的数组

相应优惠可用于的餐点类型，例如午餐或晚餐。 如果未设置，则相应优惠可应用于所有餐点类型。
restricted_to_certain_courses布尔值

相应优惠是否只能应用于特定课程。

优惠券

字段名称类型要求说明
text字符串

优惠提供方希望向用户显示的优惠券文本。
code字符串

必需

需要使用优惠券代码才能兑换优惠。 必需。

PaymentInstrument

字段名称类型要求说明
items对象数组
(PaymentInstrumentItem)

必需

可用于享受相应优惠的付款方式列表。 必需。
provider_name字符串

必需

支付方式提供方的名称。可以是银行合作伙伴、银行名称等。例如：American Express、HDFC、ICICI。 必需。

PaymentInstrumentItem

字段名称类型要求说明
type枚举
(PaymentInstrumentType)

必需

支付方式的类型。 必需。
name字符串

必需

付款方式项的名称，例如信用卡的名称。 例如：HDFC Infinia、American Express Platinum。 必需。

订阅

字段名称类型要求说明
name字符串

必需

订阅的名称。 必需。
subscription_auto_added布尔值

用户享受此优惠时是否会自动添加相应订阅
cost对象
(Money)

必需

订阅费用。 必需。
subscription_duration对象
(Duration)

必需

订阅在 subscription_cost 价格下的有效期。 必需。
terms_and_conditions_url字符串

与相应订阅相关的合作伙伴条款及条件的网址。

时长

字段名称类型要求说明
seconds字符串

时间段的带符号秒数。必须介于 -315,576,000,000 到 +315,576,000,000 之间（含边界值）。注意：这些界限是根据以下公式计算得出的：60 秒/分钟 * 60 分钟/小时 * 24 小时/天 * 365.25 天/年 * 10000 年
nanos数值

时间跨度（精确到纳秒）的有符号秒数小数部分。小于 1 秒的时长用 0 seconds 字段和正或负 nanos 字段表示。对于时长为 1 秒或更长时间的情况，nanos 字段的非零值必须与 seconds 字段的符号相同。必须介于 -999,999,999 到 +999,999,999 之间（含边界值）。

条款

字段名称类型要求说明
url字符串

合作伙伴的条款及条件的网址。
restricted_to_certain_users布尔值

优惠是否仅限特定用户使用。
terms_and_conditions字符串

合作伙伴提供的主要条款及条件文本。
additional_terms_and_conditions字符串数组

除合作伙伴的主要条款及条件之外的条款及条件。

ValidityPeriod

字段名称类型要求说明
valid_period对象
(ValidityRange)

优惠的有效开始和结束时间戳。 这些时间必须代表不同的日期，即开始时间必须为 00:00（一天的开始），结束时间必须为有效期的结束日期当天的 00:00（不含）。
time_of_day对象数组
(TimeOfDayWindow)

指定给定日期内的有效时间间隔以及可享受优惠的日期。 例如： 周一：上午 10 点至下午 5 点 周二：上午 10 点至下午 2 点 周二：下午 5 点至晚上 7 点 周三、周四、周五、周六、周日：下午 3 点至晚上 7 点 如果未设置任何时间，则表示相应优惠在 valid_period 内的任何时间均有效。
time_exceptions对象数组
(ValidTimeException)

指定上述 valid_period 和 valid_time_of_week 的例外情况

ValidityRange

一个闭开时间戳范围。

字段名称类型要求说明
valid_from_time对象
(Timestamp)

必需

范围的开始时间（含）。 必需。
valid_through_time对象
(Timestamp)

范围的结束时间（不含）。 如果未设置，则表示此时间段永不结束。 可选。

时间戳

字段名称类型要求说明
seconds字符串

表示世界协调时间 (UTC) 的秒数（从 Unix 时间 1970-01-01T00:00:00Z 开始算起）。必须介于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z 之间（含边界值）。
nanos数值

秒的非负分数（纳秒精度）。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须介于 0 到 999,999,999 之间（含边界值）。

TimeOfDayWindow

TimeWindow 对象是一个复合实体，用于描述用户订单可下单或可履单的时间段列表。

字段名称类型要求说明
time_windows对象
(TimeOfDayRange)

必需

可下单/完成订单的时间窗口。 必需。
day_of_week枚举
(DayOfWeek)的数组

应用窗口的一周中的天数列表。 如果未设置任何值，则表示该规则适用于一周中的所有天。 可选。

TimeOfDayRange

一个半开半闭的时间范围。

字段名称类型要求说明
open_time对象
(TimeOfDay)

一个时间，表示范围中一天的开始时间（含）。 如果未设置，则表示 00:00:00。 可选。
close_time对象
(TimeOfDay)

一个时间，表示范围中一天的结束时间（不含）。 如果未设置，则表示 23:59:59。 可选。

TimeOfDay

字段名称类型要求说明
hours数值

一天中的时段（采用 24 小时制）。必须大于或等于 0，且通常必须小于或等于 23。对于下班时间等场景，API 可以选择允许“24:00:00”一值。
minutes数值

一小时中的分钟数。必须大于或等于 0，且小于或等于 59。
seconds数值

一分钟中的秒数。必须大于或等于 0，通常必须小于或等于 59。如果 API 允许闰秒，则可以允许 60 一值。
nanos数值

秒数的小数部分（以纳秒为单位）。必须大于或等于 0 且小于或等于 999,999,999。

ValidTimeException

字段名称类型要求说明
exceptional_period对象
(ValidityRange)

优惠失效的开始和结束时间戳。 这些时间必须代表不同的日期，即开始时间必须为 00:00（一天的开始），结束时间必须为例外时段结束当天 00:00（不含）。

OfferSource

名称说明
OFFER_SOURCE_UNSPECIFIED
OFFER_SOURCE_AGGREGATOR

ActionType

名称说明
ACTION_TYPE_UNSPECIFIED
ACTION_TYPE_DINING

OfferMode

名称说明
OFFER_MODE_OTHER
OFFER_MODE_WALK_IN
OFFER_MODE_FREE_RESERVATION
OFFER_MODE_PAID_RESERVATION
OFFER_MODE_ONLINE_ORDER

OfferCategory

优惠类别。基本优惠是面向所有客户提供的标准优惠，例如满 100 美元立减 10%。受优惠券或付款方式限制的基本优惠将设置相应的字段。我们还提供“买满 x 即可享受优惠”的优惠，例如 ADD_ON_PAYMENT_OFFER。此类优惠可与其他优惠叠加使用，以获得额外折扣。

名称说明
OFFER_CATEGORY_UNSPECIFIED
OFFER_CATEGORY_BASE_OFFER
OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER
OFFER_CATEGORY_ADD_ON_COUPON_OFFER
OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER

FeeUnit

名称说明
FEE_UNIT_UNSPECIFIED
FEE_UNIT_PER_GUEST
FEE_UNIT_PER_TRANSACTION

FeeType

名称说明
FEE_TYPE_UNSPECIFIED
FEE_TYPE_FIXED
FEE_TYPE_VARIABLE

MealType

名称说明
MEAL_TYPE_UNSPECIFIED
MEAL_TYPE_BREAKFAST
MEAL_TYPE_LUNCH
MEAL_TYPE_DINNER

PaymentInstrumentType

名称说明
PAYMENT_INSTRUMENT_TYPE_UNSPECIFIED
PAYMENT_INSTRUMENT_CREDIT_CARD
PAYMENT_INSTRUMENT_DEBIT_CARD
PAYMENT_INSTRUMENT_BANK_ACCOUNT
PAYMENT_INSTRUMENT_UPI
PAYMENT_INSTRUMENT_ONLINE_WALLET

DayOfWeek

表示星期几。

名称说明
DAY_OF_WEEK_UNSPECIFIED未指定星期几。
MONDAY星期一
TUESDAY星期二
WEDNESDAY星期三
THURSDAY星期四
FRIDAY星期五
SATURDAY星期六
SUNDAY星期日

offer_specification

折扣可以是百分比，也可以是从总价值中减去的固定值。 例如： 1. 最终账单可享 9 折优惠。 2. 订单金额立减 15 美元。 商家还可以通过相关规范字段提供自定义折扣，例如“买一送一”。 必需。

字段名称类型要求说明
discount_percent数值

与 discount_value、other_offer_detail_text 互斥

折扣的账单百分比。 [0, 100] 对于适用于整个餐点的“买一送一”或“半价”优惠（例如“买一送一”自助餐、整个账单“买一送一”、套餐“买一送一”），此值可设置为 50。
discount_value对象
(Money)

与 discount_percent、other_offer_detail_text 互斥

折扣的固定值。
other_offer_detail_text字符串

与 discount_percent、discount_value 互斥

用于描述折扣的自由格式文本。 对于特定的“买一送一”优惠（例如“买一送一”饮品、“买一送一”主菜、“买一送一”精选菜单项），应在此处说明这些详细信息。

费用

字段名称类型要求说明
amount对象
(Money)

与 amount_range 互斥

amount_range对象
(MoneyRange)

与 amount 互斥

Feed 上传

优惠信息 Feed 必须上传到 Generic Feed SFTP 服务器。请按照如何使用通用的 Feed SFTP 服务器教程中的说明操作，并将描述符文件中的 name 设置为 google.offer。

上传频率

一般来说，Google 希望您每天上传 1 次 Feed。您可以根据自己这边优惠更新的频率来提高或降低上传频率，以确保始终保持较高的准确度。请咨询您的 Google 联系人。

数据需要几个小时才能显示在 Google 上。

提供分类功能

  • OFFER_CATEGORY_BASE_OFFER：可单独领取且不与其他任何优惠叠加使用的优惠。其中包括：
    • 整个账单的固定折扣（例如，八折优惠）
    • 订阅方案（例如，会员可获赠免费甜点）
    • 在餐厅没有其他基本优惠的情况下，付款优惠
  • 加购优惠：需要先领取基础优惠才能领取的优惠。这些内容包括：
    • OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER（例如，使用特定信用卡可享额外九折优惠）
    • OFFER_CATEGORY_ADD_ON_COUPON_OFFER（例如，使用特定优惠券代码可获赠免费饮品）
    • OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER（例如，订阅者可额外享受 10% 的折扣）

其他注意事项：

  • 如果餐厅未设置基本优惠，则不会显示加购优惠。 如果没有基础优惠，则任何无需添加到其他优惠即可申领的付款、订阅或优惠券优惠都必须标记为 OFFER_CATEGORY_BASE_OFFER。
    • 必须根据类型设置 PaymentInstrument、Subscription 或 Coupon 的相关数据。
    • 合作伙伴必须提供每种优惠的 2 份副本，以涵盖这些优惠同时作为基础优惠和加购优惠的场景。然后，您可以使用 entity_ids 或 add_on_offer_applicable_to_all_entities 为多家餐厅设置加购优惠广告内容。
  • 如果餐厅有多个可叠加的基础优惠，则所有基础优惠都应标记为 OFFER_CATEGORY_BASE_OFFER，并且属于付款、订阅或优惠券优惠的基础优惠应另外作为相关的附加优惠类型发送。
  • 只有在没有有效的基础优惠时，才应使用 ValidityPeriod 将加购项优惠作为基础优惠进行激活。

示例情形：

  • 某餐厅规定，使用特定信用卡付款可享 5% 折扣，使用特定优惠券代码可获赠免费饮品

    • 信用卡 5% 折扣优惠应以 2 份的形式发送，一份标记为 OFFER_CATEGORY_BASE_OFFER，另一份标记为 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER，并附上 PaymentInstrument 详细信息。
    • 含优惠券代码的免费饮料优惠应以 OFFER_CATEGORY_ADD_ON_COUPON_OFFER 形式发送，并附上 Coupon 详细信息。

  • 某餐厅为临时到店的顾客提供九折优惠，为使用特定信用卡的顾客提供九五折优惠，这两种优惠可以叠加使用。

    • 10% 的到店优惠应标记为 OFFER_CATEGORY_BASE_OFFER。
    • 信用卡九五折优惠应有 2 个副本，一个标记为 OFFER_CATEGORY_BASE_OFFER，另一个标记为 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER。

  • 某餐厅在工作日午餐时段提供 10% 的折扣，使用特定信用卡付款时可随时享受 5% 的折扣。

    • 10% 折扣优惠应将 ValidityPeriod 设置为仅在工作日餐厅的午餐时段有效。
    • 信用卡九五折优惠应以 2 份的形式发送。
      • 其中一个副本应标记为 OFFER_CATEGORY_BASE_OFFER，并包含 PaymentInstrument 详细信息。ValidityPeriod 应设置为在工作日排除午餐时段（当 10% 的午餐优惠有效时）
      • 其中一份应标记为 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER，并包含 PaymentInstrument 详细信息。
    • 此餐厅的所有其他付款优惠都应标记为 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER。

开发和启动流程

在整个集成过程中，合作伙伴门户能够根据您的开发情况为您提供信息和反馈。开发过程将遵循以下流程：

  • 将首先在沙盒环境中开发集成。您应在 Google 沙盒环境中使用从生产环境中导出的数据或直接使用生产环境中的数据。这有助于确保您的开发顾及到所有边缘情况，使 Google 能够评估数据质量并根据数据模型为您提供更好的帮助。
  • 您在 Google 沙盒环境中连续上传完整每日商家 Feed、服务 Feed 和交易 Feed 后，Google 团队将对您的 Feed 进行评估。经 Google 团队批准后，您可以将代码推送到生产环境，并开始将生产数据发送到 Google 生产环境中。
  • 完成对生产环境集成的全面测试后，Google 团队也将对其进行测试。完成所有测试后，系统将启动您的集成。

监控

为确保用户获得良好的体验，Google 会在发布前和发布后检查所提供的优惠是否有效、正确且符合我们的政策标准。为此，Google 将结合使用人工审核和自动化审核。您可以在 Action Center 的商品信息中心（仅限正式版）中查看这些审核的结果。此监控的结果可能会影响商品的排名。

自动检查（抓取工具）

Google 质量团队会实现抓取工具。抓取工具是一种脚本，可自动执行网络浏览器来执行一些点击操作并提取优惠信息，仅用于质量测试。

查询数

例如，如果我们决定每天发送 5,000 次检查，这意味着每天（均匀分布在一天中，即大约每 17 秒一次）我们的抓取工具会执行常规用户会执行的所有以下操作：

  • 从 Google 搜索开始，然后点击合作伙伴链接。
  • 查找优惠信息。
  • 如果优惠需要预订，系统会继续进入预订流程，以确认优惠在指定时间是否可用（不会进行预订）。

Web 数据抓取工具检测

为确保网络抓取工具不会被禁止（这可能会导致其得出优惠不可用的结论），请确保您的系统始终允许我们的网络抓取工具查询您的网页。如需识别我们的网页抓取工具，请执行以下操作：

  • 网页抓取工具 User-Agent 将包含字符串“Google-Offers”：
    • 示例：Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko; Google-Offers) Chrome/104.0.5112.101 Safari/537.36
  • 您还可以按照“验证 Googlebot 和其他 Google 抓取工具”中的建议，使用 DNS 反向查找来检查调用是否来自 Google。 在我们的具体案例中，反向 DNS 解析遵循以下模式：google-proxy-***-***-***-***.google.com。

技术行为

缓存

为了减轻合作伙伴网站的负载，我们的抓取工具通常会配置为遵循响应中存在的所有标准 HTTP 缓存标头。这意味着，对于配置正确的网站，我们会避免重复提取很少更改的内容（例如 JavaScript 库）。如需详细了解如何实现缓存，请参阅这篇 HTTP 缓存文档。