促銷活動可讓你和 Google 透過折扣價格，吸引消費者試用你的餐點訂購服務。Google 支援將訂購端對端動作與促銷活動管理系統整合。
系統支援下列折扣類型：
- Google 贊助的促銷代碼：由 Google 自動預先填入或由使用者輸入的促銷代碼。
- 第三方贊助的促銷代碼：由餐飲訂購服務供應商提供，供使用者輸入的促銷代碼。
- 第三方贊助的自動折扣：無需輸入促銷代碼，餐點訂購服務就會自動套用折扣。
無論折扣類型為何，Google 都會向你的餐飲訂購服務供應商發出結帳呼叫，以便驗證並套用折扣。
身為餐點訂購服務的開發人員，您需要對導入作業進行一些變更，才能計算有效促銷代碼的折扣，或傳送無效促銷代碼的錯誤訊息、管理促銷代碼兌換限制，以及追蹤補助費用的會計資料。
如何處理促銷活動
如要實作支援促銷活動的執行要求，請執行下列操作：
- 設定促銷活動整合。(如果您未使用 Google 贊助的促銷代碼，請略過這個步驟)。
- 導入促銷活動結帳功能。
- 實作促銷活動提交訂單功能。
設定促銷活動整合
如果您打算使用 Google 贊助的促銷代碼，本節將說明如何設定促銷活動整合功能。如果您只想支援第三方贊助的促銷代碼或折扣，可以指定自己的設定，並略過本節。
Google 會指定贊助者的促銷活動類型，並與您聯絡，以便設定整合。我們提供以下詳細資料：
- 折扣金額。
- 購物車的最低價值。
- 促銷代碼的使用開始和結束日期。
- 促銷活動預算的最高金額。
- 促銷代碼可使用的次數。
促銷代碼範例：
FopaNewUser：10% (固定百分比)，最高折扣 $50 美元。FopaMoreThan50：$10 美元 (固定折扣金額)。
如果 Google 決定停止套用代碼，我們會與您聯絡。
設定提撥
請與 Google EAP 顧問聯絡，設定撥款程序。只有在最終訂單狀態為下列任一狀態時，Google 才會退還涉及 Google 贊助促銷代碼的交易：
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
實作促銷活動結帳流程
本節說明在支援促銷代碼 (Google 贊助或第三方贊助) 時，如何實作結帳處理程序。對於第三方贊助的自動折扣，您只需在 CheckoutResponseMessage 中傳回折扣明細項目即可 (無需檢查促銷代碼)。
在處理餐點訂單時，Google 會將單一促銷代碼傳送至CheckoutRequestMessage。使用者在重複結帳時，可以變更購物車或促銷代碼。
如要確認使用者是否首次套用促銷代碼，請執行下列操作：
- Google 贊助的促銷代碼：Google 會檢查回訪使用者是否嘗試再次使用相同的促銷代碼；您不需要採取任何行動。
- 第三方贊助的促銷代碼或自動折扣：如果您未實作帳戶連結和使用者選擇加入功能，就無法在結帳要求處理期間檢查使用者的詳細資料。請改為在
SubmitOrderRequestMessage處理期間，使用FoodCartExtension物件中的Contact詳細資料 (例如使用者的電子郵件地址) 進行檢查。
根據最新的結帳要求，找出錯誤或計算滿足度折扣。請務必確保系統不會保留過時的狀態資訊。
確認優惠碼是否有效
你的服務應根據規定條款 (例如到期日、使用次數上限和折扣上限) 檢查特定促銷代碼的有效性或資格。接著，請在 CheckoutResponseMessage 中使用計算的折扣做出適當回應，如果無法套用促銷代碼，則使用 foodOrderErrors 回應。如果您發現促銷代碼有錯誤，請按照「處理促銷活動錯誤」一節所述的程序處理。
以下程式碼片段顯示促銷代碼的 foodOrderErrors 範例。請確認 correctedProposedOrder 不包含促銷活動節點。
"foodOrderErrors": [
{
"error": "PROMO_NOT_APPLICABLE",
// Copy promotions.coupon string from CheckoutRequest as the ID
"id": "GoogleNewUser",
"description": "Promotion could not be applied"
}
],
"correctedProposedOrder": {// required ...},
"paymentOptions": {// required ...}
運算折扣
如果促銷代碼有效，你的執行服務應會計算折扣美元值，並傳回 CheckoutResponseMessage，其中包含 otherItems 陣列中計算的折扣值。訂單總價不得為負值。如果折扣金額超過購物車金額，請傳回最高美元金額，讓訂單總價顯示為 $0 美元。
以下程式碼片段為促銷折扣的 CheckoutResponseMessage 段落範例：
"proposedOrder": {
"otherItems": [
. . .
{
"name": "Discount",
// copy promotions.coupon field from CheckoutRequest as the id
"id": "GoogleNewUser",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-3",
"nanos": -500000000
}
},
"type": "DISCOUNT",
}
]
}
釋出未使用的促銷活動
並非每個結帳要求都會導致提交訂單要求。如果你的服務在結帳時對促銷活動進行預留，請務必設立機制，在一段時間後，如果沒有透過提交訂單的方式兌換促銷活動，就釋出預留的金額。這可確保您的餐點訂購服務維持正確的廣告活動配額。
處理促銷活動錯誤
如果你的執行服務判定 CheckoutRequestMessage 中的促銷代碼無效 (例如已過期、無效或系統無法辨識)，請傳送 CheckoutResponseMessage，並附上包含適用錯誤代碼和原因文字的 foodOrderError，以及 correctedProposedOrder 和 paymentOptions 物件。
如果你的服務發現同一個要求有多次促銷代碼錯誤，請先傳回無法復原的錯誤，再傳回可復原的錯誤。請依下列優先順序進行檢查 (由高到低)：
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
範例
以下是含有促銷代碼的結帳要求範例：
{ "accessToken": "test_access_token", "lastSeen": "2018-06-22T19:25:39Z" }, "conversation": { "conversationId": "XYZ" }, "inputs": [ { "intent": "actions.foodordering.intent.CHECKOUT", "arguments": [ { "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.Cart", "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "name": "Falafel Tray", "type": "REGULAR", "id": "sample_item_offer_id_1", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/offer/id1", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "promotions": [ { "coupon": "FOPAACTIVECODE" } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } } } } } ] } ], "directActionOnly": true, "isInSandbox": true }
如果促銷代碼有效，以下是執行要求的對應結帳回應：
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "checkoutResponse": { "proposedOrder": { "otherItems": [ { "name": "Delivery Fees", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "3", "nanos": 500000000 } }, "type": "DELIVERY" }, { "name": "Tax", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "1", "nanos": 370000000 } }, "type": "TAX" }, { "name": "Promotion", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "-5", "nanos": 0 } }, "id": "FOPAACTIVECODE", "type": "DISCOUNT" } ], "cart": { "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "name": "Falafel Tray", "type": "REGULAR", "id": "2529103", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/offer/id1", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "promotions": [ { "coupon": "FOPAACTIVECODE" } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } } } }, "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 820000000 } }, "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension", "availableFulfillmentOptions": [ { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } }, "expiresAt": "2018-06-22T19:30:52.596Z" } ] } }, "orderOptions": {}, "paymentOptions": { "googleProvidedOptions": { "tokenizationParameters": { "tokenizationType": "PAYMENT_GATEWAY", "parameters": { "gateway": "stripe", "stripe:publishableKey": "example_stripe_client_key", "stripe:version": "2017-04-06" } }, "supportedCardNetworks": [ "AMEX", "DISCOVER", "MASTERCARD", "VISA", "JCB" ], "prepaidCardDisallowed": true } } } } } ], "suggestions": [] } } }
如果促銷代碼無效，結帳回應會如下所示：
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "error": { "foodOrderErrors": [ { "error": "PROMO_NOT_RECOGNIZED", "id": "SOMEPROMO", "description": "Coupon not found" } ], "correctedProposedOrder": { "cart": { "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "id": "sample_item_offer_id_4", "name": "Prawns Biryani", "type": "REGULAR", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "18", "nanos": 750000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/offer/id4", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "extension": { "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } }, "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension" }, "promotions": [] }, "otherItems": [ { "name": "Tax", "type": "TAX", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "1", "nanos": 650000000 } } } ], "termsOfServiceUrl": "https://exampleprovider.com/terms", "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "20", "nanos": 400000000 } }, "extension": { "availableFulfillmentOptions": [ { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "PT0M" } } } ], "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension" } }, "paymentOptions": { "googleProvidedOptions": { "prepaidCardDisallowed": false, "billingAddressRequired": true, "tokenizationParameters": { "tokenizationType": "PAYMENT_GATEWAY", "parameters": { "gateway": "braintree", "braintree:apiVersion": "v1", "braintree:sdkVersion": "1.4.0", "braintree:merchantId": "example_braintree_merchant_ID", "braintree:clientKey": "example_braintree_client_key", "braintree:authorizationFingerprint": "example_braintree_fingerprint" } } } }, "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension" } } } ] } } }
實作促銷活動訂單提交功能
在提交訂單履行時，請檢查這是否是使用者首次套用促銷代碼。在 SubmitOrderRequestMessage 處理期間，您可以使用 FoodCartExtension 物件的 Contact 詳細資料 (例如使用者的電子郵件地址) 進行檢查。
您也應重新檢查促銷代碼的適用性：
- 如果代碼適用：確認訂單並標示已兌換優待券。
- 如果代碼不再適用：拒絕使用
PROMO_NOT_APPLICABLE錯誤的訂單。您可以使用與FoodOrderUpdateExtension相同的機制，提供具體拒絕原因。
範例
以下是含有促銷活動的提交訂單要求範例：
{ "conversation": { "conversationId": "example_conversation_ID" }, "inputs": [ { "intent": "actions.intent.TRANSACTION_DECISION", "arguments": [ { "transactionDecisionValue": { "order": { "finalOrder": { "cart": { "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "name": "Falafel Tray", "type": "REGULAR", "id": "sample_item_offer_id_1", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "promotions": [ { "coupon": "FOPAACTIVECODE" } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } }, "contact": { "displayName": "Food Ordering", "email": "example.provider@gmail.com", "phoneNumber": "+19993334444", "firstName": "Food", "lastName": "Ordering" } } }, "otherItems": [ { "name": "Delivery Fees", "type": "DELIVERY", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "3", "nanos": 500000000 } } }, { "name": "Tax", "type": "TAX", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "1", "nanos": 370000000 } } }, { "name": "Promotion", "type": "DISCOUNT", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "-5" } }, "id": "FOPAACTIVECODE" }, { "name": "Subtotal", "type": "SUBTOTAL", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } } }, { "name": "Tip", "type": "GRATUITY", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD" } } } ], "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 820000000 } }, "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension" } }, "googleOrderId": "example_google_order_ID", "orderDate": "2018-06-22T19:30:59.502Z", "paymentInfo": { "displayName": "example_display_name", "googleProvidedPaymentInstrument": { "instrumentToken": "example_instrument_token" }, "paymentType": "PAYMENT_CARD" }, "locale": "en" } } } ] } ], "directActionOnly": true, "isInSandbox": true }
如果促銷代碼有效，以下是訂單執行作業的對應提交訂單回應範例：
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "orderUpdate": { "actionOrderId": "example_action_order_ID", "orderState": { "state": "CREATED", "label": "Order is created with partner." }, "updateTime": "2018-06-22T19:31:01.556Z", "orderManagementActions": [ { "type": "CALL_RESTAURANT", "button": { "title": "Call Us", "openUrlAction": { "url": "tel:+1-111-111-1111" } } }, { "type": "EMAIL", "button": { "title": "Email Us", "openUrlAction": { "url": "mailto:example.provider@gmail.com" } } }, { "type": "CUSTOMER_SERVICE", "button": { "title": "Customer Service", "openUrlAction": { "url": "http://www.google.com" } } } ] } } } ], "suggestions": [] } } }
以下是促銷代碼無效時，提交訂單的回應範例：
"orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "REJECTED", "label": "Order rejected." }, "updateTime": "2017-05-10T02:30:00.000Z", "rejectionInfo": { "type": "PROMO_NOT_APPLICABLE", "reason": "Sorry, there's something wrong. Try another code?" }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:example.provider@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+19993334444" } } } ], "infoExtension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "foodOrderErrors": [ { "error": "PROMO_USER_INELIGIBLE", "description": "Sorry, you can only use this promotion once." } ] } }