Mit Angeboten können Sie und Google Kunden dazu motivieren, Ihren Bestellservice mit reduzierten Preisen auszuprobieren. Google unterstützt die Integration Ihrer End-to-End-Aktionen für Bestellungen in Ihr Angebotsverwaltungssystem.
Die folgenden Rabattarten werden unterstützt:
- Von Google gesponserte Gutscheincodes:Gutscheincodes, die von Google automatisch vorausgefüllt oder von Nutzern eingegeben werden.
- Von Drittanbietern gesponserte Gutscheincodes:Gutscheincodes, die Nutzer einlösen können, werden von Ihrem Lebensmittelbestellservice zur Verfügung gestellt.
- Von Drittanbietern gesponserte automatische Rabatte:Rabatte, die von Ihrem Essensbestellservice automatisch ohne Gutscheincode angewendet werden.
Unabhängig von der Art des Rabatts ruft Google bei der Bestellabwicklung an der Kasse an, um den Rabatt zu prüfen und anzuwenden.
Als Entwickler eines Lebensmittelbestelldienstes müssen Sie einige Änderungen an Ihrer Implementierung vornehmen, um Rabatte für gültige Gutscheincodes zu berechnen oder Fehler bei ungültigen Gutscheincodes zu senden, Einschränkungen für die Einlösung von Gutscheincodes zu verwalten und Buchhaltungsdaten für eine Erstattung zu verfolgen.
So verarbeiten Sie Angebote
So implementieren Sie eine Auftragsausführung, die Angebote unterstützt:
- Richten Sie Angebote ein. Überspringen Sie diesen Schritt, wenn Sie keine von Google gesponserten Gutscheincodes verwenden.
- Implementieren Sie den Bezahlvorgang mit Angeboten.
- Implementieren Sie die Funktion „Bestellung aufgeben“ mit Angeboten.
Integration von Angeboten einrichten
In diesem Abschnitt wird beschrieben, wie Sie die Integration von Angeboten einrichten, wenn Sie von Google gesponserte Gutscheincodes verwenden möchten. Wenn Sie nur Gutscheincodes oder Rabatte unterstützen möchten, die von einem Drittsponsor unterstützt werden, können Sie Ihre eigene Einrichtung vornehmen und diesen Abschnitt überspringen.
Google legt die Art der Werbeaktion fest, die gesponsert werden soll, und kontaktiert Sie, um die Integration einzurichten. Wir geben die folgenden Informationen an:
- Der Rabattbetrag.
- Der Mindesteinkaufswert.
- Das Start- und Enddatum für die Verwendung der Gutscheincodes.
- Der maximale Eurobetrag, der für die Werbekampagne vorgesehen ist.
- Gibt an, wie oft die Gutscheincodes verwendet werden können.
Beispiele für Gutscheincodes:
FopaNewUser: 10% (fester Prozentsatz) mit maximal 50 $Rabatt.FopaMoreThan50: 10 € (fester Betrag)
Falls Google die Anwendung des Codes aussetzen sollte, 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 einen der folgenden Status hat:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Bezahlvorgang mit Angeboten implementieren
In diesem Abschnitt wird beschrieben, wie Sie die Zahlungsabwicklung implementieren, wenn Sie Gutscheincodes (von Google oder von Drittanbietern) unterstützen. Bei von Drittanbietern gesponserten automatischen Rabatten müssen Sie nur die Rabattposition in der CheckoutResponseMessage zurückgeben. Eine Überprüfung des Gutscheincodes ist nicht erforderlich.
Während der Essensbestellung sendet Google einen einzelnen Gutscheincode in der CheckoutRequestMessage an die Auftragsausführung. Nutzer können den Einkaufswagen oder den Gutscheincode bei wiederholten Zahlungsanfragen ändern.
So prüfen Sie, ob der Nutzer zum ersten Mal einen Gutscheincode eingelöst hat:
- Von Google gesponserte Gutscheincodes: Google prüft, ob ein wiederkehrender Nutzer versucht, denselben Gutscheincode noch einmal zu verwenden. Sie müssen nichts unternehmen.
- Von Drittanbietern gesponserte Gutscheincodes oder automatische Rabatte: Wenn du die Kontoverknüpfung und Zustimmung des Nutzers nicht implementiert hast, kannst du die Details des Nutzers bei der Bearbeitung von Zahlungsanfragen nicht prüfen. Prüfen Sie das stattdessen während der
SubmitOrderRequestMessage-Verarbeitung mithilfe derContact-Details (z. B. die E-Mail-Adresse des Nutzers) aus demFoodCartExtension-Objekt.
Identifizieren Sie Fehler oder berechnen Sie Rabatte mit Ihrer Auftragsausführung auf der Grundlage der letzten Zahlungsanforderung. Achten Sie dabei darauf, dass Ihr System keine veralteten Statusinformationen speichert.
Gültigkeit des Gutscheincodes prüfen
Die Auftragsausführung sollte die Gültigkeit oder die Eignung eines bestimmten Gutscheincodes anhand der vorgegebenen Bedingungen prüfen, z. B. dem Ablaufdatum, der maximalen Nutzung und dem maximalen Rabatt. Antworten Sie dann im CheckoutResponseMessage entsprechend mit dem berechneten Rabatt oder mit foodOrderErrors, wenn der Gutscheincode nicht angewendet werden kann. Wenn Sie Fehler im Zusammenhang mit dem Aktionscode feststellen, folgen Sie der Anleitung unter Fehler bei Angeboten beheben.
Das folgende Snippet zeigt ein foodOrderErrors-Beispiel für einen Gutscheincode.
Achten Sie darauf, dass correctedProposedOrder nicht den Angebotsknoten enthält.
"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 Aktionscode gültig ist, sollte die Auftragsausführung den Rabattwert in Dollar berechnen und ein CheckoutResponseMessage mit dem berechneten Rabattwert im Array otherItems zurücksenden. Der Gesamtpreis der Bestellung darf nicht negativ sein. Wenn der Rabattbetrag den Warenkorbbetrag übersteigt, sende den maximalen Betrag zurück, um den Gesamtpreis der Bestellung auf 0 $zu berechnen.
Das folgende Snippet zeigt ein Beispiel für einen CheckoutResponseMessage-Abschnitt 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 Werbeaktionen freigeben
Nicht jede Bezahlanfrage führt zu einer Bestellanfrage. Wenn ein Angebot durch die Auftragsausführung zum Zeitpunkt des Anrufs ausgesetzt wird, sollten Sie eine Möglichkeit haben, die Aussetzung aufzuheben, wenn das Angebot nicht nach einem bestimmten Zeitraum über eine Bestellung in Anspruch genommen wird. So sorgen Sie dafür, dass Ihr Essensbestellservice das richtige Kampagnenkontingent einhält.
Fehler bei Angeboten beheben
Wenn die Auftragsausführung feststellt, dass der Gutscheincode eines CheckoutRequestMessage ungültig ist (z. B. abgelaufen, ungültig oder nicht erkannt), senden Sie eine CheckoutResponseMessage mit einer foodOrderError, die den entsprechenden Fehlercode und den Grundtext sowie die Objekte correctedProposedOrder und paymentOptions enthält.
Wenn bei der Auftragsausführung in derselben Anfrage mehrere Fehler mit Gutscheincodes auftreten, senden Sie die nicht behebbaren Fehler erst zurück, nachdem Sie das Problem behoben haben. Priorisieren Sie die Prüfungen wie folgt (von hoher zu niedriger Priorität):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Beispiele
Hier ist 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
}
Wenn der Gutscheincode gültig ist, siehst du die entsprechende Antwort der Auftragsausführung an der Kasse:
{
"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 sehen Sie ein Beispiel für eine Checkout-Antwort, 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 senden“ mit Angeboten implementieren
Prüfen Sie bei der Auftragsabwicklung, ob der Nutzer zum ersten Mal einen Gutscheincode anwendet. Während der Verarbeitung von SubmitOrderRequestMessage können Sie dies mithilfe der Contact-Details (z. B. die E-Mail-Adresse des Nutzers) aus dem FoodCartExtension-Objekt prüfen.
Prüfen Sie außerdem noch einmal die Anwendbarkeit des Gutscheincodes:
- Wenn der Code anwendbar 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 mit derselben Methode wie fürFoodOrderUpdateExtensioneinen spezifischen Ablehnungsgrund angeben.
Beispiele
Hier ist ein Beispiel für eine Anfrage zum Aufgeben einer Bestellung 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 Anfrage zum Senden einer Bestellung, 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 sehen Sie ein Beispiel für die Antwort auf „Bestellung senden“, 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."
}
]
}
}