Mit Angeboten können Sie und Google Kunden mit Rabatten dazu anregen, Ihren Lieferservice für Essen auszuprobieren. Google unterstützt die Einbindung Ihrer End-to-End-Aktionen für Bestellungen in Ihr Angebotsverwaltungssystem.
Die folgenden Rabatttypen werden unterstützt:
- Von Google gesponserte Gutscheincodes:Gutscheincodes, die automatisch von Google ausgefüllt oder von Nutzern eingegeben werden.
- Von Drittanbietern gesponserte Gutscheincodes:Gutscheincodes, die Nutzer eingeben können und die von Ihrem Lieferservice bereitgestellt werden.
- Von Drittanbietern gesponserte automatische Rabatte:Rabatte, die Ihr Lieferservice automatisch ohne Gutscheincode anwendet.
Unabhängig von der Art des Rabatts sendet Google einen Checkout-Aufruf an Ihren Dienstleister für die Essensbestellung, um den Rabatt zu prüfen und anzuwenden.
Als Entwickler eines Lieferservice für Lebensmittel müssen Sie einige Änderungen an Ihrer Implementierung vornehmen, um Rabatte für gültige Gutscheincodes zu berechnen oder Fehler für ungültige Gutscheincodes zu senden, Einschränkungen bei der Einlösung von Gutscheincodes zu verwalten und Buchhaltungsdaten für die Erstattung zu erfassen.
Angebote verarbeiten
So implementieren Sie eine Auftragsausführung, die Angebote unterstützt:
- Richten Sie die Integration von Angeboten ein. (Überspringen Sie diesen Schritt, wenn Sie keine von Google gesponserten Gutscheincodes verwenden.)
- Bezahlvorgang mit Angeboten implementieren
- Implementieren Sie „Bestellung mit Angeboten senden“.
Integration von Angeboten einrichten
In diesem Abschnitt wird beschrieben, wie Sie die Einbindung von Angeboten einrichten, wenn Sie von Google gesponserte Angebotscodes verwenden möchten. Wenn Sie nur Gutscheincodes oder Rabatte unterstützen möchten, die von einem Drittanbieter gesponsert werden, können Sie Ihre eigene Einrichtung festlegen und diesen Abschnitt überspringen.
Google gibt den Typ der Werbeaktion an, die gesponsert werden soll, und kontaktiert dich, um die Integration einzurichten. Wir stellen folgende Informationen zur Verfügung:
- Der Rabattbetrag.
- Der Mindestwert für den Warenkorb.
- Das Start- und Enddatum für die Verwendung der Gutscheincodes.
- Der maximale Budgetbetrag in US-Dollar für die Angebotskampagne.
- Wie oft die Gutscheincodes verwendet werden können.
Beispiele für Gutscheincodes:
FopaNewUser: 10% (fester Prozentsatz) mit einem maximalen Rabatt von 50 $.FopaMoreThan50: 10 € (fester Rabattbetrag).
Sollte Google die Anwendung des Codes beenden, werden Sie benachrichtigt.
Auszahlungen einrichten
Wenden Sie sich an Ihren Google EAP-Berater, um die Auszahlung einzurichten. Google erstattet nur Transaktionen mit von Google gesponserten Gutscheincodes, wenn der endgültige Bestellstatus einer der folgenden ist:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Kasse mit Angeboten implementieren
In diesem Abschnitt wird beschrieben, wie Sie die Zahlungsabwicklung implementieren, wenn Sie Gutscheincodes (von Google oder Drittanbietern gesponsert) unterstützen. Bei automatischen Rabatten, die von Drittanbietern gesponsert werden, müssen Sie nur die Rabattposition in der CheckoutResponseMessage zurückgeben. Eine Überprüfung des Gutscheincodes ist nicht erforderlich.
Bei der Auftragsausführung für Essensbestellungen sendet Google einen einzelnen Gutscheincode im Feld CheckoutRequestMessage an die Auftragsausführung. Nutzer können ihren Einkaufswagen oder Gutscheincode bei wiederholten Bezahlanfragen ändern.
So prüfen Sie, ob der Nutzer zum ersten Mal einen Gutscheincode angewendet hat:
- Von Google gesponserte Gutscheincodes: Google prüft, ob ein wiederkehrender Nutzer versucht, denselben Gutscheincode noch einmal zu verwenden. Sie müssen nichts weiter tun.
- Von Drittanbietern gesponserte Gutscheincodes oder automatische Rabatte: Wenn Sie die Kontoverknüpfung und die Nutzeraktivierung nicht implementiert haben, können Sie die Details des Nutzers bei der Verarbeitung der Zahlungsanfrage nicht prüfen. Prüfe stattdessen während der
SubmitOrderRequestMessage-Verarbeitung, ob das der Fall ist. Verwende dazu dieContact-Details (z. B. die E-Mail-Adresse des Nutzers) aus demFoodCartExtension-Objekt.
Fehler erkennen oder Rabatte mithilfe der letzten Direktkaufanfrage berechnen Achten Sie dabei darauf, dass Ihr System keine veralteten Statusinformationen speichert.
Gültigkeit des Gutscheincodes prüfen
Bei der Abwicklung sollte die Gültigkeit oder Berechtigung eines bestimmten Aktionscodes anhand der angegebenen Bedingungen geprüft werden, z. B. Ablaufdatum, maximale Nutzung und maximaler Rabatt. Gib dann in CheckoutResponseMessage den berechneten Rabatt oder foodOrderErrors zurück, wenn der Aktionscode nicht angewendet werden kann. Wenn Sie Fehler mit dem Gutscheincode feststellen, folgen Sie der Anleitung unter Fehler bei Angeboten beheben.
Das folgende Snippet zeigt ein Beispiel für foodOrderErrors für einen Gutscheincode.
Der Knoten „Angebote“ darf nicht in correctedProposedOrder enthalten sein.
"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 ...}
Compute-Rabatte
Wenn der Gutscheincode gültig ist, sollte dein Fulfillment-System den Rabattwert in US-Dollar berechnen und eine CheckoutResponseMessage mit dem berechneten Rabattwert im otherItems-Array zurücksenden. Der Gesamtbestellpreis darf nicht negativ sein. Wenn der Rabatt den Betrag im Einkaufswagen übersteigt, sende den maximalen Dollarbetrag zurück, damit der Gesamtbestellpreis 0 $beträgt.
Das folgende Snippet zeigt einen Beispielabschnitt CheckoutResponseMessage für den Aktionsrabatt:
"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",
}
]
}
Nicht verwendete Angebote freigeben
Nicht jede Zahlungsanfrage führt zu einer Bestellanfrage. Wenn Ihr Fulfillment-Center bei der Kasse eine Vorautorisierung für ein Angebot vornimmt, muss es einen Mechanismus geben, mit dem die Vorautorisierung aufgehoben wird, wenn das Angebot nach einem bestimmten Zeitraum nicht über die Bestellung geltend gemacht wird. So wird sichergestellt, dass Ihr Lieferservice das richtige Kampagnenlimit einhält.
Fehler bei Angeboten verarbeiten
Wenn bei der Abwicklung festgestellt wird, dass der Gutscheincode aus einer CheckoutRequestMessage ungültig ist (z. B. abgelaufen, ungültig oder nicht erkannt), sende eine CheckoutResponseMessage mit einer foodOrderError, die den entsprechenden Fehlercode und den Grund enthält, sowie correctedProposedOrder- und paymentOptions-Objekte.
Wenn bei der Auftragsausführung mehrere Gutscheincodefehler für dieselbe Anfrage gefunden werden, senden Sie zuerst die nicht wiederherstellbaren Fehler zurück, bevor Sie die wiederherstellbaren Fehler zurücksenden. Priorisieren Sie die Prüfungen so (von hoher zu niedriger Priorität):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Beispiele
Hier ein Beispiel für eine Zahlungsanfrage mit einem Gutscheincode:
{ "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 }
Hier ist die entsprechende Zahlungsantwort der Auftragsausführung, wenn der Gutscheincode gültig ist:
{ "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": [] } } }
Hier ein Beispiel für eine Antwort beim Bezahlvorgang, wenn der Gutscheincode ungültig ist:
{ "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" } } } ] } } }
„Bestellung mit Angeboten senden“ implementieren
Prüfe bei der Auftragsausführung, ob der Nutzer zum ersten Mal einen Gutscheincode anwendet. Während der Verarbeitung von SubmitOrderRequestMessage kannst du dies anhand der Contact-Details (z. B. der E-Mail-Adresse des Nutzers) aus dem FoodCartExtension-Objekt prüfen.
Prüfen Sie auch noch einmal, ob der Gutscheincode gültig ist:
- Wenn der Code gültig ist:Bestätige die Bestellung und markiere den Gutschein als eingelöst.
- Wenn der Code nicht mehr gültig ist:Lehne die Bestellung mit dem Fehler
PROMO_NOT_APPLICABLEab. Sie können einen bestimmten Ablehnungsgrund angeben, indem Sie denselben Mechanismus wie fürFoodOrderUpdateExtensionverwenden.
Beispiele
Hier ein Beispiel für eine Bestellanfrage mit Angeboten:
{ "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 }
Hier ist ein Beispiel für die entsprechende Antwort auf die Bestellung von einem Fulfillment-Anbieter, wenn der Gutscheincode gültig ist:
{ "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": [] } } }
Hier ein Beispiel für die Antwort, wenn der Gutscheincode ungültig ist:
"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." } ] } }