促销活动让您和 Google 能够激励客户以折扣价格试用您的订餐服务。Google 支持您将 Google Actions 订单与促销活动管理系统集成。
支持以下类型的折扣:
- Google 赞助的促销代码:由 Google 自动预填充或用户输入的促销代码。
- 第三方赞助的促销代码:用户输入的促销代码,由您的订餐服务提供。
- 第三方赞助的自动折扣:您的订餐服务会自动应用折扣,无需提供促销代码。
无论折扣类型如何,Google 都会为您的订餐履单结账,以验证并应用折扣。
作为订餐服务的开发者,您需要对实现进行一些更改,以计算有效促销代码的折扣、针对无效促销代码发送错误、管理促销代码兑换限制,以及跟踪会计报销数据。
如何处理促销活动
如需实现支持促销活动的执行方式,请执行以下操作:
- 设置促销活动集成。(如果您使用的不是 Google 赞助的促销代码,请跳过此步骤。)
- 使用促销活动实现结账。
- 实现促销活动的提交订单。
设置促销活动集成
本部分介绍了如何使用 Google 赞助的促销代码设置促销活动集成。如果您只想支持第三方赞助商提供的促销代码或折扣,可以指定您自己的设置并跳过本部分。
Google 指定要赞助的促销活动的类型,并与您联系以设置集成。我们提供以下详细信息:
- 折扣金额。
- 最低购物车价值。
- 使用促销代码的开始日期和结束日期。
- 促销活动的预算上限(以美元为单位)。
- 促销代码可以使用的次数。
促销代码示例:
FopaNewUser
:10%(固定百分比),最高可减 50 美元。FopaMoreThan50
:10 美元(优惠固定金额)。
如果 Google 决定停止使用相应代码,会与您联系。
设置付款
请与您的 Google EAP 顾问联系,以设置付款流程。 仅当最终订单状态为以下之一时,Google 才会对涉及 Google 赞助促销代码的交易进行退款:
CONFIRMED
IN_TRANSIT
READY_FOR_PICKUP
IN_PREPARATION
FULFILLED
使用促销活动功能实现结账
本部分介绍了在您支持促销代码(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 ...}
计算折扣
如果促销代码有效,您的执行方式应计算折扣金额值,并在 otherItems
数组中发回带有计算得出的折扣值的 CheckoutResponseMessage
。订单总价不能为负数。如果折扣金额超过购物车金额,请发回最高美元金额,将总订单价格呈现为 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
的促销代码无效(例如,代码已过期、无效或无法识别),请发送包含 foodOrderError
(包含适用错误代码和原因文本)的 correctedProposedOrder
和 paymentOptions
对象。CheckoutResponseMessage
如果您的执行方式发现同一请求中有多个促销代码错误,请发回不可恢复的错误,然后再发回可恢复的错误。 按以下方式确定检查的优先级(从高到低):
PROMO_NOT_RECOGNIZED
PROMO_EXPIRED
PROMO_USER_INELIGIBLE
PROMO_ORDER_INELIGIBLE
PROMO_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." } ] } }