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 di ordini con il sistema di gestione delle promozioni.
Sono supportati i seguenti tipi di sconti:
- Codici promozionali sponsorizzati da Google: codici promozionali precompilati automaticamente da Google o inseriti dagli utenti.
- Codici promozionali sponsorizzati da terze parti:codici promozionali da inserire da parte degli utenti, fornito dal tuo servizio di ordinazione di cibo.
- Sconti automatici sponsorizzati da terze parti:sconti applicati automaticamente dal tuo servizio di ordinazione di cibo senza un codice promozionale.
Indipendentemente dal tipo di sconto, Google effettua una chiamata di pagamento al tuo Fulfillment per le ordinazioni 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 gli sconti per i 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'evasione che supporti le promozioni:
- Configura l'integrazione delle promozioni. Ignora questo passaggio se non utilizzi i codici promozionali sponsorizzati da Google.
- Implementare il pagamento con le 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 i codici promozionali sponsorizzati da Google. Se vuoi supportare solo i codici promozionali o gli sconti sponsorizzati da terze parti, 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 in dollari previsto 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 $ (importo fisso dello sconto).
Se Google decide di interrompere l'applicazione del codice, ti contatteremo.
Configurare i pagamenti
Contatta il tuo consulente Google EAP per configurare la procedura di pagamento. Google rimborsa le transazioni che coinvolgono i codici promozionali sponsorizzati da Google solo se lo stato dell'ordine finale è 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 i codici promozionali (sponsorizzati da Google o da terze parti). Per gli sconti automatici sponsorizzati da terze parti, devi solo restituire la voce di sconto in CheckoutResponseMessage (non è necessario controllare il codice promozionale).
Durante l'evasione degli ordini di cibo, Google invia un singolo codice promozionale nel messaggio CheckoutRequestMessage al tuo partner di evasione. 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 applica un codice promozionale, procedi come segue:
- Codici promozionali sponsorizzati da Google: Google controlla se un utente di ritorno sta tentando di utilizzare di nuovo 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 degli utenti, non potrai controllare i dettagli dell'utente durante l'elaborazione della richiesta di pagamento. Controlla invece se si verifica durante l'elaborazione di
SubmitOrderRequestMessage, utilizzando i dettagliContact(ad esempio l'indirizzo email dell'utente) dell'oggettoFoodCartExtension.
Identifica gli errori o calcola gli sconti con l'evasione degli ordini in base all'ultima richiesta di pagamento. In questo modo, assicurati che il sistema non mantenga informazioni obsolete sullo stato.
Verificare la validità del codice promozionale
L'evasione dell'ordine deve verificare la validità o l'idoneità di un determinato codice promozionale in base ai termini stipulati, ad esempio la data di scadenza, l'utilizzo massimo e lo sconto massimo. Quindi, rispondi in modo appropriato in CheckoutResponseMessage
con lo sconto calcolato o con foodOrderErrors se il codice promozionale
non può essere applicato. Se rilevi errori con il codice promozionale, segui la procedura descritta in Gestire gli errori relativi alle 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 il calcolo
Se il codice promozionale è valido, l'elaborazione deve calcolare il valore dello sconto in dollari e inviare 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 nuovamente l'importo massimo in dollari per impostare il prezzo totale dell'ordine su 0 $.
Lo snippet seguente mostra un esempio di sezione CheckoutResponseMessage 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 le promozioni inutilizzate
Non tutte le richieste di pagamento generano una richiesta di invio dell'ordine. Se il tuo Fulfillment blocca una promozione al momento della chiamata di pagamento, assicurati di avere un meccanismo per annullare la preautorizzazione se la promozione non viene richiesta tramite l'invio dell'ordine dopo un determinato periodo di tempo. In questo modo, il tuo servizio di ordinazione di cibo mantiene la quota corretta della campagna.
Gestire gli errori relativi alle promozioni
Se l'erogazione determina che il codice promozionale di un
CheckoutRequestMessage non è valido (ad esempio, è scaduto, non è valido o non è riconosciuto), invia un CheckoutResponseMessage con un foodOrderError
che contenga il codice di errore e il testo del motivo applicabili, insieme agli oggetti
correctedProposedOrder e paymentOptions.
Se l'elaborazione trova più errori relativi al codice promozionale nella stessa richiesta, invia gli errori non recuperabili prima di inviare quelli recuperabili. Assegna le priorità ai controlli come segue (dalla priorità più alta a quella 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 di pagamento corrispondente dell'evasione 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": [] } } }
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" } } } ] } } }
Implementare l'invio dell'ordine con le promozioni
Nella procedura di invio dell'ordine, controlla se è la prima volta che l'utente applica un codice promozionale. Durante l'elaborazione di SubmitOrderRequestMessage, puoi verificare questo aspetto utilizzando i dettagli di Contact (ad esempio l'indirizzo email dell'utente) dall'oggetto FoodCartExtension.
Ti consigliamo inoltre di verificare di nuovo l'applicabilità del codice promozionale:
- Se il codice è applicabile: conferma l'ordine e contrassegna il coupon come 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 diFoodOrderUpdateExtension.
Esempi
Ecco un esempio di richiesta di invio dell'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 da un'attività di 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": [] } } }
Ecco un esempio di risposta 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." } ] } }