Le promozioni offrono a te e a Google un modo per incentivare i clienti a prova il servizio di ordinazione di cibo a prezzi scontati. Google supporta integrando le Azioni end-to-end degli ordini con la gestione delle promozioni di un sistema operativo completo.
Sono supportati i seguenti tipi di sconti:
- Codici promozionali sponsorizzati da Google: codici promozionali che vengono automaticamente precompilati da Google o inseriti dagli utenti.
- Codici promozionali sponsorizzati di terze parti: codici promozionali che gli utenti possono inserire, forniti dal tuo servizio di ordinazione di cibo.
- Sconti automatici sponsorizzati da terze parti: sconti che i tuoi prodotti alimentari servizio di ordinazione si applica automaticamente senza un codice promozionale.
Indipendentemente dal tipo di sconto, Google effettua una chiamata al pagamento del tuo cibo evasione dell'ordine per verificare e applicare lo sconto.
In qualità di sviluppatore di un servizio di ordinazione di cibo, devi apportare alcune modifiche alla tua implementazione per calcolare gli sconti per codici promozionali validi o inviare errori relativi a codici promozionali non validi, gestisci l'utilizzo dei codici promozionali limitazioni e tenere traccia dei dati contabili per il rimborso.
Come elaborare le promozioni
Per implementare un evasione degli ordini che supporti le promozioni:
- Configurare l'integrazione delle promozioni. (Salta se non utilizzi i codici promozionali sponsorizzati da Google).
- Implementare il pagamento con promozioni.
- Implementa l'invio dell'ordine con le promozioni.
Configurare l'integrazione delle promozioni
Questa sezione descrive come configurare l'integrazione delle promozioni se prevedi di utilizzare Codici promozionali sponsorizzati da Google. Se vuoi supportare solo i codici promozionali o che una terza parte sponsorizza, puoi specificare la tua configurazione e saltare questa sezione.
Google specifica il tipo di promozione per lo sponsor e ti contatta per impostare l'integrazione. Forniamo i seguenti dettagli:
- L'importo dello sconto.
- Il valore minimo del carrello.
- Le date di inizio e di fine per l'utilizzo dei codici promozionali.
- L'importo massimo preventivato per la campagna promozionale.
- Il numero di volte in cui è possibile utilizzare i codici promozionali.
Esempi di codici promozionali:
FopaNewUser: 10% (percentuale fissa) con massimo 50 $di sconto.FopaMoreThan50: 10 $ (importo fisso di sconto).
Qualora Google decidesse di interrompere l'applicazione del codice, la contatteremo.
Configura i pagamenti
Contatta il tuo consulente EAP Google per configurare il processo di pagamento. Google rimborsa solo le transazioni relative a una promozione sponsorizzata da Google se lo stato finale dell'ordine è uno dei seguenti:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implementare il pagamento con le promozioni
Questa sezione descrive l'implementazione dell'elaborazione del pagamento quando supporti
codici promozionali (sponsorizzati da Google o da terze parti). Per
sconti automatici sponsorizzati da terze parti, devi restituire solo lo sconto
in CheckoutResponseMessage (nessun controllo del codice promozionale è
necessaria).
Durante l'evasione degli ordini di cibo, Google invia un unico codice promozionale nella
CheckoutRequestMessage al completamento. Gli utenti possono modificare il carrello
codice promozionale per richieste di pagamento ripetute.
Per verificare se è la prima volta che l'utente applica un codice promozionale, procedi nel seguente modo: seguenti:
- Codici promozionali sponsorizzati da Google: Google controlla se un utente di ritorno è provare a utilizzare nuovamente lo stesso codice promozionale; non devi fare nulla.
- Codici promozionali o sconti automatici sponsorizzati da terze parti: se hai
il collegamento dell'account e l'attivazione dell'utente non sono stati implementati, non potrai controllare
i dati dell'utente durante l'elaborazione della richiesta di pagamento. Controlla invece
durante l'elaborazione di
SubmitOrderRequestMessage, utilizzandoContact(come l'indirizzo email dell'utente) dalFoodCartExtension.
Identifica gli errori o calcola gli sconti per l'evasione degli ordini in base alle ultime richiesta di pagamento. Durante l'operazione, assicurati che l'impianto non sia inattivo le informazioni sullo stato.
Verifica la validità del codice promozionale
L'evasione degli ordini deve verificare la validità o l'idoneità di una determinata promozione
codice in base ai termini stipulati, come la data di scadenza, l'utilizzo massimo e
sconto massimo. Dopodiché rispondi in modo appropriato nel CheckoutResponseMessage
allo sconto calcolato o con foodOrderErrors se il codice promozionale
non possono essere applicati. Se rilevi errori nel codice promozionale, segui le
descritta nella sezione Gestire gli errori relativi alle promozioni.
Il seguente snippet mostra un esempio foodOrderErrors di un codice promozionale.
Assicurati che correctedProposedOrder non includa le promozioni
nodo.
"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 ...}
Sconti per computing
Se il codice promozionale è valido, l'evasione dell'ordine dovrebbe calcolare lo sconto
valore monetario e restituisci un CheckoutResponseMessage con il valore
nell'array otherItems. Il prezzo totale dell'ordine non deve essere
negativo. Se l'importo dello sconto supera l'importo del carrello, restituisci il
importo massimo in dollari per far sì che il prezzo totale dell'ordine sia pari a $0.
Il seguente snippet mostra una sezione CheckoutResponseMessage di esempio per
lo sconto promozionale:
"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",
}
]
}
Rilascia le promozioni non utilizzate
Non tutte le richieste di pagamento portano a una richiesta di invio dell'ordine. Se l'evasione dell'ordine sospende una promozione al momento della chiamata, assicurati di avere meccanismo di rilascio della sospensione se la promozione non viene rivendicata tramite inviare l'ordine dopo un determinato periodo di tempo. In questo modo viene assicurato il servizio di ordinazione mantiene la quota corretta della campagna.
Gestire gli errori relativi alle promozioni
Se l'evasione degli ordini determina che il codice promozionale di un
CheckoutRequestMessage non è valido (ad esempio, è scaduto, non valido,
o non riconosciuti), invia un CheckoutResponseMessage con un foodOrderError
che contenga il codice di errore e il testo del motivo applicabili, oltre
correctedProposedOrder e paymentOptions oggetti.
Se l'evasione degli ordini riscontra più errori relativi ai codici promozionali della stessa richiesta, restituire gli errori irreversibili prima di restituire quelli recuperabili. Definisci le priorità dei controlli nel seguente modo (dalla più alta alla più bassa):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Esempi
Ecco un esempio di richiesta di pagamento con un codice promozionale:
{ "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 }
Ecco la risposta al pagamento corrispondente relativa all'evasione dell'ordine se la promozione codice è valido:
{ "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": [] } } }
Ecco un esempio di risposta al pagamento se il codice promozionale non è valido:
{ "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" } } } ] } } }
Implementa l'invio dell'ordine con le promozioni
Quando invii l'ordine, controlla se è la prima volta che
l'utente sta applicando un codice promozionale. Durante SubmitOrderRequestMessage
in fase di elaborazione, puoi verificarlo utilizzando i dettagli di Contact (come
l'indirizzo email dell'utente) dall'oggetto FoodCartExtension.
Ti consigliamo inoltre di ricontrollare l'applicabilità del codice promozionale:
- Se il codice è applicabile:conferma l'ordine e contrassegna il coupon utilizzato.
- Se il codice non è più applicabile:rifiuta l'ordine utilizzando il metodo
Errore
PROMO_NOT_APPLICABLE. Puoi specificare un motivo di rifiuto specifico utilizzando lo stesso meccanismo diFoodOrderUpdateExtension.
Esempi
Ecco un esempio di richiesta di invio di un ordine con promozioni:
{ "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 }
Ecco un esempio della risposta di invio dell'ordine corrispondente di un evasione degli ordini se il codice promozionale è valido:
{ "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": [] } } }
Ecco un esempio di risposta all'ordine di invio se il codice promozionale non è valido:
"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." } ] } }