As promoções são uma forma de você e o Google incentivarem os clientes a testarem seu serviço de pedidos de comida com preços com desconto. O Google oferece suporte à integração das ações de pedidos de ponta a ponta com o sistema de gerenciamento de promoções.
Os seguintes tipos de descontos são aceitos:
- Códigos promocionais patrocinados pelo Google:códigos promocionais que são preenchidos automaticamente pelo Google ou inseridos pelos usuários.
- Códigos promocionais patrocinados por terceiros:códigos promocionais para os usuários inserirem, fornecidos pelo seu serviço de pedidos de comida.
- Descontos automáticos patrocinados por terceiros:descontos que seu serviço de pedidos de comida aplica automaticamente sem um código de promoção.
Independentemente do tipo de desconto, o Google faz uma chamada de finalização de compra para o atendimento de pedidos de comida para verificar e aplicar o desconto.
Como desenvolvedor de um serviço de pedidos de comida, você precisa fazer algumas mudanças na implementação para calcular descontos para códigos de promoção válidos ou enviar erros para códigos de promoção inválidos, gerenciar limitações de resgate de códigos de promoção e acompanhar dados contábeis para reembolso.
Como processar promoções
Para implementar um fulfillment compatível com promoções, faça o seguinte:
- Configurar a integração de promoções. Pule esta etapa se você não estiver usando códigos promocionais patrocinados pelo Google.
- Implementar a finalização da compra com promoções.
- Implementar o envio de pedidos com promoções.
Configurar a integração de promoções
Esta seção descreve como configurar a integração de promoções se você planeja usar códigos de promoção patrocinados pelo Google. Se você quiser oferecer apenas códigos de promoção ou descontos patrocinados por terceiros, especifique sua própria configuração e pule esta seção.
O Google especifica o tipo de promoção para o patrocinador e entra em contato com você para configurar a integração. Fornecemos os seguintes detalhes:
- O valor do desconto.
- O valor mínimo do carrinho.
- As datas de início e término para usar os códigos promocionais.
- O valor máximo orçado para a campanha de promoção.
- O número de vezes que os códigos promocionais podem ser usados.
Exemplos de códigos promocionais:
FopaNewUser: 10% (porcentagem fixa) com desconto máximo de US $50.FopaMoreThan50: R$ 10 (valor fixo de desconto).
Se o Google decidir interromper a aplicação do código, você vai receber um contato.
Configurar pagamentos
Entre em contato com seu consultor do EAP do Google para configurar o processo de pagamento. O Google só reembolsa transações que envolvem códigos de promoção patrocinados pelo Google se o status final do pedido for um dos seguintes:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implementar a finalização da compra com promoções
Esta seção descreve a implementação do processamento de finalização de compra quando você oferece suporte a
códigos promocionais (patrocinados pelo Google ou por terceiros). Para
descontos automáticos patrocinados por terceiros, você só precisa retornar o item de linha de desconto
no CheckoutResponseMessage. Não é necessário verificar o código de promoção.
Durante o fulfillment de pedidos de comida, o Google envia um único código promocional no
CheckoutRequestMessage para o fulfillment. Os usuários podem mudar o carrinho ou
o código promocional em solicitações de finalização de compra repetidas.
Para verificar se essa é a primeira vez que o usuário usou um código promocional, faça o seguinte:
- Códigos promocionais patrocinados pelo Google: o Google verifica se um usuário recorrente está tentando usar o mesmo código promocional novamente. Você não precisa fazer nada.
- Cupons de terceiros ou descontos automáticos: se você não tiver implementado a vinculação de contas e a ativação do usuário, não será possível verificar os detalhes do usuário durante o processamento da solicitação de finalização de compra. Em vez disso, verifique isso
durante o processamento de
SubmitOrderRequestMessage, usando os detalhesContact(como o endereço de e-mail do usuário) do objetoFoodCartExtension.
Identifique erros ou calcule descontos com a entrega com base na solicitação de finalização de compra mais recente. Ao fazer isso, verifique se o sistema não mantém informações de estado desatualizadas.
Verificar a validade do código promocional
A geração de fulfillment precisa verificar a validade ou a qualificação de um determinado código de promoção
com base nos termos estipulados, como a data de validade, o uso máximo e
o desconto máximo. Em seguida, responda adequadamente no CheckoutResponseMessage
com o desconto computado ou com foodOrderErrors se o código promocional
não puder ser aplicado. Se você detectar erros com o código promocional, siga o
processo descrito em Lidar com erros nas promoções.
O snippet a seguir mostra um exemplo de foodOrderErrors para um código de promoção.
Verifique se o correctedProposedOrder não inclui o nó de
promoções.
"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 ...}
Descontos de computação
Se o código promocional for válido, o fulfillment vai calcular o valor do desconto
em dólares e enviar de volta um CheckoutResponseMessage com o valor do desconto
calculado na matriz otherItems. O preço total do pedido não pode ser
negativo. Se o valor do desconto exceder o valor do carrinho, envie de volta o
valor máximo em dólares para que o preço total do pedido seja de US $0.
O snippet a seguir mostra um exemplo de seção CheckoutResponseMessage para
o desconto 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",
}
]
}
Liberar promoções não usadas
Nem toda solicitação de finalização de compra resulta em uma solicitação de envio de pedido. Se a entrega puser uma promoção em espera no momento da chamada de finalização da compra, tenha um mecanismo para liberar a retenção se a promoção não for reivindicada por envio de pedido após um determinado período. Isso garante que seu serviço de pedidos de comida mantenha a cota correta da campanha.
Processar erros com promoções
Se o fulfillment determinar que o código de promoção de um
CheckoutRequestMessage não é válido (por exemplo, se ele expirou, é inválido
ou não foi reconhecido), envie um CheckoutResponseMessage com um foodOrderError
que contenha o código de erro e o texto do motivo aplicáveis, junto com
os objetos correctedProposedOrder e paymentOptions.
Se o fulfillment encontrar vários erros de código de promoção na mesma solicitação, envie de volta os erros irreversíveis antes de enviar os erros recuperáveis. Priorize suas verificações da seguinte maneira (da mais alta para a mais baixa prioridade):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Exemplos
Confira um exemplo de solicitação de finalização de compra com um 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 }
Confira a resposta de finalização de compra correspondente do fulfillment se o código de promoção for válido:
{ "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": [] } } }
Confira um exemplo de resposta de finalização de compra se o código de promoção for invá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" } } } ] } } }
Implementar o envio de pedidos com promoções
Ao enviar o atendimento do pedido, verifique se é a primeira vez que o
usuário está usando um código promocional. Durante o processamento de SubmitOrderRequestMessage, é possível verificar isso usando os detalhes Contact (como o
endereço de e-mail do usuário) do objeto FoodCartExtension.
Verifique novamente a aplicabilidade do código promocional:
- Se o código for aplicável:confirme o pedido e marque o cupom como resgatado.
- Se o código não for mais aplicável:rejeite o pedido com o
erro
PROMO_NOT_APPLICABLE. Você pode informar um motivo específico de rejeição usando o mesmo mecanismo deFoodOrderUpdateExtension.
Exemplos
Confira um exemplo de envio de solicitação de pedido com promoções:
{ "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 }
Confira um exemplo da resposta de envio de pedido correspondente de um fulfillment se o código de promoção for 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": [] } } }
Confira um exemplo de resposta de envio de pedido se o código de promoção for invá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." } ] } }