總覽

參與優惠整合服務的合作夥伴在開始之前，必須先完成商家或實體 (試用版) 的帳戶設定整合步驟。本指南將詳細說明如何導入、測試和推出優惠整合服務。在執行整合步驟之前，請詳閱這份總覽和優惠政策。

優惠

優惠整合服務可讓你在特定時間點， 轉發適用於特定服務的商家促銷及折扣相關的結構化資訊。「優惠」是由實際優惠 (折扣百分比、折扣價格等)、有效期 (具體時間、星期幾等)，以及適用的用途 (像是優惠僅適用於特定服務) 所構成，也可能包含複雜的限制組合。

優惠範例：

  • 12 月的星期三和星期四中午 12 點到下午 5 點，開胃菜五折
  • 母親節晚上 6 點到 10 點晚餐時段，甜點買一送一
  • 每週日上午 10 點到下午 2 點早午餐小菜折扣 NT$150 元
  • 10% 的到店折扣，可與頂級訂閱者 5% 的折扣，以及透過應用程式付款時 5% 的折扣併用。

優惠必須符合技術資料模型，並達到 資格規定，才能納入整合服務中。請務必 詳閱我們的優惠政策， 確保您的整合作業符合規定，並瞭解 該如何處理不符合技術規定的優惠。

優惠導入作業

優惠整合服務包含兩種動態饋給，每天都會上傳，或以確保高準確度 (即減少過時) 的頻率上傳：

OfferFeed

欄位名稱類型規定說明
data物件陣列
(Offer)

優惠

欄位名稱類型規定說明
offer_id字串

必填

優惠的專屬 ID。 必填。
entity_ids字串陣列

參與這項優惠的商家清單。
add_on_offer_applicable_to_all_entities布林值

如果為 true，這項優惠適用於匯總器下的所有實體。 僅適用於加購優惠。
offer_sourceenum
(OfferSource)

必填

優惠可能由集結網站、個別商家提供，甚至由第三方以加購形式提供。必填。
action_typeenum
(ActionType)

必填

提供優惠的服務。offer_id 只能屬於一個 action_type。如果優惠可跨多種服務類型共用，則預期會為每種服務類型建立具有專屬 ID 的重複優惠。必填。
offer_modes列舉陣列
(OfferMode)

必填

提供優惠的方式，例如親自前往、預約、線上等。必要。
offer_categoryenum
(OfferCategory)

必填

優惠類別。 必填。
source_assigned_priority數字

非負整數 ([1-100]，其中 1 代表最高優先順序)，表示來源指派的方案優先順序。如果同一商家提供多項商品，這項屬性會成為商品排序的信號。0 代表未設定優先順序。
offer_detailsobject
(OfferDetails)

必填

優惠詳細資料，例如折扣、預訂費用等。必要。
offer_restrictionsobject
(OfferRestrictions)

必填

說明優惠限制，例如是否需要訂閱/付款工具、這項優惠是否可與其他優惠合併使用 (以及哪些類型) 等。 必要。
couponobject
(Coupon)

優待券詳細資料。 如果 offer_category 為 OFFER_CATEGORY_ADD_ON_COUPON_OFFER，則為必填欄位。
payment_instrumentobject
(PaymentInstrument)

付款方式的詳細資料。 如果 offer_category 為 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER，則為必填欄位。
subscriptionobject
(Subscription)

訂閱詳細資料。 如果 offer_category 為 OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER，則為必填欄位。
termsobject
(Terms)

必填

優惠條款及細則。 必填。
validity_periods物件陣列
(ValidityPeriod)

必填

優惠效期。說明優惠的有效時間範圍，包括開始和結束時間、星期幾等。為必填欄位。
offer_url字串

商家優惠頁面的網址。 如果 offer_category 為 OFFER_CATEGORY_BASE_OFFER，則為必填欄位。
image_url字串

商家優惠圖片的網址。

OfferDetails

欄位名稱類型規定說明
offer_display_text字串

必填

供應商希望在搜尋結果網頁上向消費者顯示的優惠文字。必填。
oneOf
(offer_specification)

必填

這個 oneOf 中的欄位只能設定一個。
max_discount_valueobject
(Money)

可享有的最高折扣。例如：最高可享 $100 美元的 9 折優惠。
min_spend_valueobject
(Money)

享有折扣的最低消費金額。 例如：總價滿 $100 美元可享 9 折優惠。
booking_costobject
(Money)

預訂這項優惠的費用。舉例來說，以 $15 美元的價格預訂座位，即可在結帳時享有 $100 美元的折扣。
booking_cost_unitenum
(FeeUnit)

預訂費用的單位。例如每人每筆交易。
convenience_feeobject
(Fee)

booking_cost_adjustable布林值

預訂費用是否可調整，也就是從最終帳單中扣除預訂費用。例如： 預訂晚餐可享 7 折優惠。預訂費用為 $15 美元，這筆費用會計入最終帳單。因此最終帳單為：總支出 - 30% - $15 美元
additional_fees物件陣列
(AdditionalFee)

向使用者收取的額外費用。 例如便利性、處理方式等。

金額

代表金額與其貨幣類型。

欄位名稱類型規定說明
currency_code字串

ISO 4217 定義的貨幣代碼，由 3 個字母組成。
units字串

金額的整數單位。 舉例來說，如果 currencyCode 為 "USD"，則 1 個單位為 1 美元。
nanos數字

金額的十億分之一 (10^-9) 單位數量。 這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。如果 units 為正值，nanos 必須為正值或零。 如果 units 為零，則 nanos 可為正值、零或負值。 如果 units 為負值，nanos 就必須為負值或零。 例如，$-1.75 美元的表記方式為 units=-1 和 nanos=-750,000,000。

費用

欄位名稱類型規定說明
unitenum
(FeeUnit)

typeenum
(FeeType)

oneOf
(cost)

這個 oneOf 中的欄位只能設定一個。

MoneyRange

欄位名稱類型規定說明
min_amountobject
(Money)

max_amountobject
(Money)

AdditionalFee

欄位名稱類型規定說明
name字串

必填

額外費用的名稱。例如手續費、處理費等。 必填。
feeobject
(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_restrictionsobject
(FoodOfferRestrictions)

餐飲優惠的專屬限制。

OfferCondition

欄位名稱類型規定說明
description字串

FoodOfferRestrictions

欄位名稱類型規定說明
meal_types列舉陣列
(MealType)

可套用優惠的餐點類型，例如午餐或晚餐。 如未設定，優惠可套用至所有餐點類型。
restricted_to_certain_courses布林值

優惠是否僅適用於特定課程。

優待券

欄位名稱類型規定說明
text字串

優惠供應商想向使用者顯示的優待券文字。
code字串

必填

必須使用優待券代碼才能兌換優惠。 必填。

PaymentInstrument

欄位名稱類型規定說明
items物件陣列
(PaymentInstrumentItem)

必填

可用於兌換優惠的付款方式清單。 必填。
provider_name字串

必填

付款方式供應商名稱。可以是銀行合作夥伴、銀行名稱等。例如：American Express、HDFC、ICICI。必填。

PaymentInstrumentItem

欄位名稱類型規定說明
typeenum
(PaymentInstrumentType)

必填

付款工具類型。 必填。
name字串

必填

付款方式項目的名稱，例如信用卡名稱。 例如：HDFC Infinia、American Express Platinum。 必填。

訂閱

欄位名稱類型規定說明
name字串

必填

訂閱項目名稱。 必填。
subscription_auto_added布林值

使用者兌換這項優惠時，系統是否會自動新增訂閱項目
costobject
(Money)

必填

訂閱費用。 必填。
subscription_durationobject
(Duration)

必填

訂閱方案的效期，以 subscription_cost 為準。 必填。
terms_and_conditions_url字串

合作夥伴條款及細則的網址，與這項訂閱方案相關。

時間長度

欄位名稱類型規定說明
seconds字串

時間範圍的簽署秒數。必須介於 -315,576,000,000 至 +315,576,000,000 之間 (含這兩個值)。注意：這些界限是根據以下項目計算得出： 60 秒/分鐘 * 60 分鐘/小時 * 24 小時/天 * 365.25 天/年 * 10000 年
nanos數字

時間跨度以奈秒為單位的正負秒數。如果時間長度不到一秒，系統會以 0 seconds 欄位和正數或負數 nanos 欄位表示。如果時間長度為一秒以上，nanos 欄位的非零值必須與 seconds 欄位相同。值必須介於 -999,999,999 到 +999,999,999 之間 (含)。

條款

欄位名稱類型規定說明
url字串

合作夥伴條款及細則的網址。
restricted_to_certain_users布林值

優惠是否僅限特定使用者。
terms_and_conditions字串

合作夥伴提供的主要條款及細則文字。
additional_terms_and_conditions字串陣列

除了合作夥伴的主要條款及細則外，還須遵守其他條款及細則。

ValidityPeriod

欄位名稱類型規定說明
valid_periodobject
(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_timeobject
(Timestamp)

必填

範圍的開始時間 (含)。 必填。
valid_through_timeobject
(Timestamp)

範圍的結束時間 (不含)。 如未設定，表示這段期間永不結束。 選填。

時間戳記

欄位名稱類型規定說明
seconds字串

代表自 Unix 紀元 (1970-01-01T00:00:00Z) 起算的世界標準時間秒數。必須介於 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z 之間 (含)。
nanos數字

以奈秒為單位的非負秒數小數。如果秒數值為負數，且包含小數，奈秒值仍須為非負數，且時間會往前計算。值必須介於 0 到 999,999,999 之間 (含)。

TimeOfDayWindow

TimeWindow 物件是複合實體，用於說明使用者訂單可下單或完成的時段清單。

欄位名稱類型規定說明
time_windowsobject
(TimeOfDayRange)

必填

可下單/完成訂單的時間範圍。 必填。
day_of_week列舉陣列
(DayOfWeek)

時段適用的每週天數清單。 如未設定，則表示適用於一週的每一天。 選填。

TimeOfDayRange

封閉式開放時間範圍。

欄位名稱類型規定說明
open_timeobject
(TimeOfDay)

時間，表示範圍當天的開始時間 (含)。 如果未設定，則表示 00:00:00。 選填。
close_timeobject
(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_periodobject
(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 美元可享 9 折優惠。如果基本方案受到優待券或付款方式限制，系統會設定相應的欄位。我們也提供加購方案，例如 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週四
FRIDAYFriday (週五)
SATURDAYSaturday (週六)
SUNDAY星期日

offer_specification

折扣可以是百分比，也可以是從總值扣除的固定值。例如： 1. 最終結算金額可享 9 折優惠。 2. 訂單現折 $15 美元。 商家也可以透過相關規格欄位提供自訂折扣，例如「買一送一」。必填。

欄位名稱類型規定說明
discount_percent數字

與 discount_value、other_offer_detail_text 互斥

帳單的折扣百分比。 [0, 100] 如為適用於整餐的買一送一或半價優惠 (例如：買一送一自助餐、買一送一整筆帳單、買一送一套餐)，這個值可以設為 50。
discount_valueobject
(Money)

與 discount_percent、other_offer_detail_text 互斥

折扣的固定值。
other_offer_detail_text字串

與 discount_percent、discount_value 互斥

自由輸入文字，說明折扣。 如果是特定 1+1 優惠 (例如買一送一飲料、加購主餐、買一送一指定菜單項目)，請在此處說明這些詳細資料。

費用

欄位名稱類型規定說明
amountobject
(Money)

與 amount_range 互斥

amount_rangeobject
(MoneyRange)

與 amount 互斥

動態饋給上傳

優惠動態饋給必須上傳至 Generic 動態饋給安全檔案傳輸通訊協定伺服器。請按照「如何使用一般動態饋給 SFTP 伺服器教學課程」中的說明操作，並在描述元檔案中將 name 設為 google.offer。

上傳頻率

一般來說，Google 每天會上傳 1 個動態饋給。視你更新方案的頻率而定，上傳頻率可能會增加或減少，確保準確度維持在高水準。請洽詢您的 Google 合作夥伴業務聯絡人。

資料會在幾小時後顯示在 Google 上。

提供分類

  • OFFER_CATEGORY_BASE_OFFER：可單獨兌換的優惠，不必與其他優惠併用。包括：
    • 帳單總額的固定折扣 (例如8 折優惠)
    • 訂閱優惠 (例如(會員可享免費甜點)
    • 如果餐廳沒有其他基本優惠，則提供付款優惠
  • 加購優惠：必須先兌換基本優惠才能兌換的優惠。包括：
    • OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER (例如 使用特定信用卡可享額外 9 折優惠
    • OFFER_CATEGORY_ADD_ON_COUPON_OFFER (例如 使用特定優待券代碼可免費兌換飲料)
    • OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER (例如 訂閱者可享額外 9 折優惠

其他注意事項：

  • 如果餐廳未設定基本方案，就不會顯示加購方案。 如果沒有基本方案，任何可單獨兌換的付款、訂閱或優待券優惠，都必須標示為 OFFER_CATEGORY_BASE_OFFER。
    • 視類型而定，必須設定 PaymentInstrument、Subscription 或 Coupon 的相關資料。
    • 合作夥伴必須提供每項優惠的 2 份副本，以涵蓋同時做為基本優惠和加購優惠的情況。然後使用 entity_ids 或 add_on_offer_applicable_to_all_entities，為多間餐廳設定加購優惠文案。
  • 如果餐廳有多個可疊加的基本方案，所有基本方案都應標記為 OFFER_CATEGORY_BASE_OFFER，且付款、訂閱或優待券基本方案應額外以相關加購方案類型傳送。
  • ValidityPeriod 應僅用於啟用加購優惠，做為基本優惠，前提是沒有有效的基本優惠。

情境示例：

  • 餐廳提供特定信用卡付款 95 折優惠，以及使用特定優待券代碼可免費兌換飲料

    • 5% 信用卡折扣優惠應以 2 份副本的形式傳送，其中一份標記為 OFFER_CATEGORY_BASE_OFFER，另一份標記為 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER，並附上 PaymentInstrument 詳細資料。
    • 如果優惠是提供免費飲料，且須使用優待券代碼，請以 OFFER_CATEGORY_ADD_ON_COUPON_OFFER 形式傳送，並附上Coupon詳細資料。

  • 餐廳提供 9 折優惠給上門顧客，並提供 95 折優惠給使用特定信用卡付款的顧客，這兩項優惠可合併使用。

    • 10% 的店內優惠應標記為 OFFER_CATEGORY_BASE_OFFER。
    • 信用卡 95 折優惠應有 2 份副本，其中一份標記為 OFFER_CATEGORY_BASE_OFFER，另一份標記為 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER。

  • 餐廳提供平日午餐 9 折優惠，以及使用特定信用卡付款時的 95 折優惠。

    • 10% 折扣優惠應ValidityPeriod設定為僅在平日午餐時段提供。
    • 信用卡 95 折優惠應以 2 份副本的形式傳送。
      • 其中一份副本應標示為 OFFER_CATEGORY_BASE_OFFER，並附上 PaymentInstrument 詳細資料。ValidityPeriod 應設為在平日午餐時段排除放送，以啟用午餐 9 折優惠
      • 其中一份副本應標記為 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER，並附上 PaymentInstrument 詳細資料。
    • 這間餐廳的其他所有付款優惠都應標示為 OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER。

開發與上線程序

在整個整合過程中，您都可以透過合作夥伴入口網站，依據自己的開發情況取得相關的資訊和意見回饋協助。開發程序會按以下流程進行：

  • 先在沙箱環境中開發整合服務。您應該 在 Google 沙箱環境中使用產品匯出功能 (或甚至 直接使用產品資料)。這有助於確保您的開發作業涵蓋到所有邊緣情況，並讓 Google 評估資料品質，進而根據您的資料模型提供更好的協助。
  • 當您開始持續將完整的每日「商家」、「服務」和「優惠」動態饋給 上傳到 Google 沙箱環境，Google 團隊就會評估您的 動態饋給。等 Google 團隊提供核准，您就可以將程式碼推送到正式環境，並開始將產品資料傳送到 Google 實際執行環境。
  • 當您完整測試「正式版」整合服務後，Google 團隊也會進行測試。等所有測試都完成後，您的整合服務就可以上線。

監控

為確保使用者體驗良好，Google 會在發布前後檢查提供的優惠是否有效、正確且符合政策條件。為此，Google 會結合人工和自動化審查。審查結果會顯示在行動中心 (僅限正式版) 的方案資訊主頁中。這項監控的結果可能會影響商品排名的升降。

自動檢查 (檢索器)

Google 品質團隊會導入檢索器。檢索器是自動執行網頁瀏覽器指令碼，可點擊網頁並擷取產品資訊，僅供品質測試之用。

查詢次數

舉例來說，如果我們決定每天傳送 5000 次檢查，表示我們的檢索器每天會執行 5000 次使用者會執行的所有動作 (平均分配在一天內，大約每 17 秒一次)：

  • 從 Google 搜尋開始，然後點選合作夥伴連結。
  • 尋找優惠資訊。
  • 如果優惠需要預訂，系統會繼續進行預訂流程，確認優惠在指定時間是否適用 (不會實際預訂)。

偵測網頁資料擷取工具

為確保網頁抓取工具不會遭到封鎖 (這可能會導致系統判定優惠不適用)，請確認系統允許網頁抓取工具隨時查詢你的網頁。如何辨識我們的網頁抓取工具：

  • 網頁檢索器 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 快取說明文件。