Las promociones proporcionan una forma para que tú y Google incentiven a los clientes a probar tu servicio de pedidos de comida con precios con descuento. Google admite la integración de tus Acciones de extremo a extremo de pedidos con el sistema de administración de promociones.
Se admiten los siguientes tipos de descuentos:
- Códigos promocionales patrocinados por Google: Son códigos que Google completa previamente de forma automática o que ingresan los usuarios.
- Códigos promocionales patrocinados por terceros: Son códigos promocionales que proporciona tu servicio de pedidos de comida para que los usuarios ingresen.
- Descuentos automáticos patrocinados por terceros: Son descuentos que tu servicio de pedidos de comida aplica automáticamente sin un código promocional.
Sin importar el tipo de descuento, Google realiza una llamada de confirmación de la compra a la entrega de tu pedido de comida para verificar y aplicar el descuento.
Como desarrollador de un servicio de pedido de comida, debes realizar algunos cambios en tu implementación para calcular descuentos para códigos promocionales válidos o enviar errores por códigos promocionales no válidos, administrar las limitaciones de canje de códigos promocionales y realizar un seguimiento de los datos de contabilización para el reembolso.
Cómo procesar las promociones
Para implementar una entrega que admita promociones, haz lo siguiente:
- Configura la integración de promociones. (Omite este paso si no usas códigos promocionales patrocinados por Google).
- Implementa la confirmación de la compra con promociones.
- Implementa el envío de pedidos con promociones.
Configura la integración de promociones
En esta sección, se describe cómo configurar la integración de promociones si planeas usar códigos promocionales patrocinados por Google. Si solo deseas admitir códigos promocionales o descuentos que patrocina un tercero, puedes especificar tu propia configuración y omitir esta sección.
Google especifica el tipo de promoción que patrocinarás y se comunica contigo para configurar la integración. Proporcionamos los siguientes detalles:
- Es el importe del descuento.
- El valor mínimo del carrito
- Corresponde a las fechas de inicio y finalización para usar los códigos promocionales.
- El importe máximo en dólares presupuestado para la campaña promocional.
- Indica la cantidad de veces que se pueden usar los códigos promocionales.
Ejemplos de códigos promocionales:
FopaNewUser: 10% (porcentaje fijo) con un máximo de USD 50 de descuento.FopaMoreThan50: USD 10 (importe fijo de descuento).
Si Google decide detener la aplicación del código, nos comunicaremos contigo.
Configurar los desembolsos
Comuníquese con su asesor de Google EAP para configurar el proceso de desembolso. Google solo reembolsa las transacciones que involucran códigos promocionales de Google si el estado final del pedido es uno de los siguientes:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implementa la confirmación de la compra con promociones
En esta sección, se describe cómo implementar el procesamiento de la confirmación de la compra cuando admites códigos promocionales (patrocinados por Google o por terceros). Para los descuentos automáticos patrocinados por terceros, solo debes mostrar la línea de pedido de descuento en el CheckoutResponseMessage (no es necesario verificar el código promocional).
Durante la entrega de un pedido de comida, Google envía un solo código promocional en el CheckoutRequestMessage a tu entrega. Los usuarios pueden cambiar su carrito o código promocional en solicitudes repetidas de confirmación de la compra.
Para verificar si es la primera vez que el usuario aplica un código promocional, haz lo siguiente:
- Códigos promocionales patrocinados por Google: Google verifica si un usuario recurrente intenta usar el mismo código promocional nuevamente; no necesitas hacer nada.
- Códigos promocionales patrocinados por terceros o descuentos automáticos: Si no implementaste la vinculación de cuentas y la participación del usuario, no podrás verificar los detalles del usuario durante el procesamiento de la solicitud de confirmación de la compra. En cambio, comprueba esto durante el procesamiento de
SubmitOrderRequestMessage. Para ello, usa los detalles deContact(como la dirección de correo electrónico del usuario) del objetoFoodCartExtension.
Identifica errores o calcula descuentos con tu entrega según la solicitud de confirmación de la compra más reciente. Cuando lo hagas, asegúrate de que tu sistema no conserve información de estado inactivo.
Verifica la validez del código promocional
Tu entrega debe verificar la validez o elegibilidad de un código promocional determinado con las condiciones estipuladas, como la fecha de vencimiento, el uso máximo y el descuento máximo. Luego, responde de forma apropiada en el CheckoutResponseMessage con el descuento calculado o con foodOrderErrors si no se puede aplicar el código promocional. Si detectas errores en el código promocional, sigue el proceso que se describe en Soluciona errores con las promociones.
En el siguiente fragmento, se muestra un ejemplo de foodOrderErrors para un código promocional.
Asegúrate de que correctedProposedOrder no incluya el nodo de promociones.
"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 ...}
Descuentos de Compute
Si el código promocional es válido, tu entrega debe calcular el valor en dólares de descuento y devolver un CheckoutResponseMessage con el valor de descuento calculado en el array otherItems. El precio total del pedido no debe ser negativo. Si el importe del descuento supera el importe del carrito, devuelve el importe máximo en dólares para que el precio total del pedido sea USD 0.
En el siguiente fragmento, se muestra un ejemplo de una sección CheckoutResponseMessage para el descuento promocional:
"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",
}
]
}
Publicar promociones sin usar
No todas las solicitudes de confirmación de la compra generan solicitudes de envío de pedidos. Si tu entrega pone en espera una promoción durante la llamada de confirmación de la compra, asegúrate de contar con un mecanismo para liberar la retención si no se reclama la promoción mediante el envío de un pedido después de un período determinado. Esto garantiza que tu servicio de pedido de comida mantenga la cuota de campaña correcta.
Soluciona errores con las promociones
Si tu entrega determina que el código promocional de un CheckoutRequestMessage no es válido (por ejemplo, está vencido, no es válido o no se reconoce), envía un CheckoutResponseMessage con un foodOrderError que contenga el código de error y el texto del motivo, junto con los objetos correctedProposedOrder y paymentOptions.
Si tu entrega encuentra varios errores de códigos promocionales en la misma solicitud, envía de vuelta los errores irrecuperables antes de volver a enviar los errores recuperables. Prioriza tus verificaciones de la siguiente manera (de prioridad alta a baja):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Ejemplos
Este es un ejemplo de una solicitud de confirmación de la compra con un código promocional:
{
"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
}
Si el código promocional es válido, esta es la respuesta de confirmación de la compra correspondiente de la entrega:
{
"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": []
}
}
}
A continuación, se incluye un ejemplo de una respuesta de confirmación de la compra si el código promocional no es válido:
{
"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 el pedido de envío con promociones
En la entrega de tu pedido, verifica si es la primera vez que el usuario aplica un código promocional. Durante el procesamiento de SubmitOrderRequestMessage, puedes verificar esto con los detalles de Contact (como la dirección de correo electrónico del usuario) del objeto FoodCartExtension.
También debe volver a verificar la aplicabilidad del código promocional:
- Si el código es aplicable: Confirma el pedido y marca el cupón canjeado.
- Si el código ya no es aplicable: Rechaza el pedido con el error
PROMO_NOT_APPLICABLE. Puedes proporcionar un motivo específico del rechazo con el mismo mecanismo que paraFoodOrderUpdateExtension.
Ejemplos
A continuación, se incluye un ejemplo de una solicitud de envío de pedido con promociones:
{
"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
}
Este es un ejemplo de la respuesta de pedido de envío correspondiente de una entrega si el código promocional es válido:
{
"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": []
}
}
}
A continuación, se incluye un ejemplo de la respuesta de envío de pedido si el código promocional no es válido:
"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."
}
]
}
}