Le promozioni consentono a te e a Google di incentivare i clienti a provare il tuo servizio di ordinazione di cibo con prezzi scontati. Google supporta l'integrazione delle azioni end-to-end degli ordini con il sistema di gestione delle promozioni.
Sono supportati i seguenti tipi di sconti:
- Codici promozionali sponsorizzati da Google: codici promozionali che vengono precompilati automaticamente da Google o inseriti dagli utenti.
- Codici promozionali sponsorizzati da terze parti: codici promozionali che gli utenti possono inserire, forniti dal servizio di ordinazione di cibo.
- Sconti automatici sponsorizzati da terze parti: sconti che il tuo servizio di ordinazione di cibo applica automaticamente senza un codice promozionale.
Indipendentemente dal tipo di sconto, Google effettua una chiamata di pagamento all'evasione degli ordini di cibo 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 sconti per codici promozionali validi o inviare errori per i codici promozionali non validi, gestire le limitazioni di utilizzo dei codici promozionali e monitorare i dati contabili per il rimborso.
Come elaborare le promozioni
Per implementare un fulfillment che supporti le promozioni:
- Configurare l'integrazione delle promozioni. Ignora questo passaggio se non utilizzi i codici promozionali sponsorizzati da Google.
- Implementa il pagamento con promozioni.
- Implementa l'opzione di invio dell'ordine con promozioni.
Configurare l'integrazione delle promozioni
Questa sezione descrive come configurare l'integrazione delle promozioni se prevedi di utilizzare i codici promozionali sponsorizzati da Google. Se vuoi supportare solo i codici promozionali o gli sconti sponsorizzati da una terza parte, puoi specificare la tua configurazione e saltare questa sezione.
Google specifica il tipo di promozione da sponsorizzare e ti contatta per configurare 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 uno sconto massimo di 50 $.FopaMoreThan50: 10 $ (sconto fisso).
Nel caso in cui Google decidesse di interrompere l'applicazione del codice, ti contatteremo.
Configura i pagamenti
Contatta il tuo consulente EAP Google per configurare la procedura di pagamento. Google rimborsa le transazioni che includono codici promozionali sponsorizzati da Google solo se lo stato finale dell'ordine è uno dei seguenti:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implementa il pagamento con promozioni
Questa sezione descrive l'implementazione dell'elaborazione del pagamento quando supporti i codici promozionali (sponsorizzati da Google o da terze parti). Per
gli sconti automatici sponsorizzati da terze parti, devi solo restituire l'elemento pubblicitario
scontato nella CheckoutResponseMessage (non è necessario verificare
il codice promozionale).
Durante l'evasione degli ordini di cibo, Google invia un singolo codice promozionale nel CheckoutRequestMessage al tuo evasione degli ordini. Gli utenti possono modificare il carrello o
il codice promozionale in caso di richieste di pagamento ripetute.
Per verificare se è la prima volta che l'utente ha applicato un codice promozionale:
- Codici promozionali sponsorizzati da Google: Google controlla se un utente di ritorno sta provando di nuovo a utilizzare lo stesso codice promozionale; non devi fare nulla.
- Codici promozionali sponsorizzati da terze parti o sconti automatici: se
non hai implementato il collegamento dell'account e l'attivazione da parte dell'utente, non potrai controllare
i dettagli dell'utente durante l'elaborazione della richiesta di pagamento. Controlla invece questo aspetto durante l'elaborazione di
SubmitOrderRequestMessage, utilizzando i dettagliContact(come l'indirizzo email dell'utente) dall'oggettoFoodCartExtension.
Identifica gli errori o calcola sconti con il tuo evasione degli ordini in base all'ultima richiesta di pagamento. Durante questa operazione, assicurati che il sistema non conservi informazioni aggiornate sullo stato.
Verificare la validità del codice promozionale
L'evasione degli ordini deve verificare la validità o l'idoneità di un determinato codice promozionale rispetto ai termini concordati, come la data di scadenza, l'utilizzo massimo e lo sconto massimo. Quindi, rispondi correttamente nella CheckoutResponseMessage con lo sconto calcolato o con foodOrderErrors se non è possibile applicare il codice promozionale. Se rilevi errori nel codice promozionale, segui la procedura descritta in Gestire gli errori delle promozioni.
Lo snippet seguente mostra un esempio di foodOrderErrors per un codice promozionale.
Assicurati che correctedProposedOrder non includa il nodo Promozioni.
"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, il fulfillment deve calcolare il valore monetario dello sconto e restituire un CheckoutResponseMessage con il valore dello sconto calcolato nell'array otherItems. Il prezzo totale dell'ordine non deve essere
negativo. Se l'importo dello sconto supera l'importo del carrello, invia l'importo massimo in dollari per ottenere il prezzo totale dell'ordine 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",
}
]
}
Rilasciare promozioni inutilizzate
Non tutte le richieste di pagamento portano a una richiesta di invio di un ordine. Se l'evasione degli ordini sospende una promozione al momento della chiamata di pagamento, assicurati di disporre di un meccanismo per annullare la sospensione nel caso in cui la promozione non venga rivendicata tramite l'invio dell'ordine dopo un determinato periodo di tempo. Ciò garantisce che il servizio di ordinazione di cibo mantenga la quota corretta di campagne.
Gestire gli errori delle promozioni
Se il fulfillment determina che il codice promozionale di un CheckoutRequestMessage non è valido (ad esempio è scaduto, non è valido o non è riconosciuto), invia un CheckoutResponseMessage con un foodOrderError contenente il codice di errore applicabile e il testo del motivo, insieme agli oggetti correctedProposedOrder e paymentOptions.
Se il fulfillment rileva più errori di codici promozionali nella stessa richiesta, invia nuovamente gli errori irreversibili prima di riinviare gli errori recuperabili. Definisci le priorità dei controlli nel modo seguente (da alta a 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 dal fulfillment, se il codice promozionale è 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": []
}
}
}
Di seguito è riportato 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"
}
}
}
]
}
}
}
Implementare l'invio dell'ordine con promozioni
Nell'evasione dell'ordine di invio, controlla se è la prima volta che l'utente applica un codice promozionale. Durante l'elaborazione di SubmitOrderRequestMessage, puoi verificarlo utilizzando i dettagli Contact (ad esempio l'indirizzo email dell'utente) dall'oggetto FoodCartExtension.
Ti consigliamo anche 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 con l'errore
PROMO_NOT_APPLICABLE. Puoi fornire un motivo di rifiuto specifico utilizzando lo stesso meccanismo utilizzato perFoodOrderUpdateExtension.
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 all'ordine di invio corrispondente relativa a un evasione 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": []
}
}
}
Di seguito è riportato un esempio della risposta relativa all'invio dell'ordine 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."
}
]
}
}