Les promotions vous permettent, à vous et à Google, d'inciter les clients à essayez votre service de commande de repas avec des tarifs réduits. Google prend en charge intégrer vos actions de commande de bout en bout à la gestion des promotions du système d'exploitation.
Les types de remises suivants sont acceptés:
- Codes promotionnels sponsorisés par Google:codes promotionnels générés automatiquement prérempli par Google ou saisi par les utilisateurs.
- Codes promotionnels tiers:codes promotionnels que les utilisateurs peuvent saisir fournies par votre service de commande de repas.
- Remises automatiques sponsorisées par un tiers:remises sur vos repas de commande s'applique automatiquement sans code promotionnel.
Quel que soit le type de remise, Google passe un appel le traitement des commandes pour vérifier et appliquer la remise.
En tant que développeur d'un service de commande de repas, vous devez apporter quelques modifications à votre mise en œuvre pour calculer les remises pour les codes promotionnels valides ou envoyer erreurs en cas de codes promotionnels non valides, gérer l'utilisation des codes promotionnels les restrictions et suivre les données comptables dans le cadre des remboursements.
Traiter les promotions
Pour implémenter un traitement prenant en charge les promotions, procédez comme suit:
- Configurez l'intégration des promotions. (Passer cette étape à l'étape précédente si vous n'utilisez pas les codes promotionnels sponsorisés par Google).
- Implémentez le paiement avec promotions.
- Implémentez l'option "Envoyer la commande avec des promotions".
Configurer l'intégration des promotions
Cette section explique comment configurer l'intégration des promotions si vous prévoyez d'utiliser Codes promotionnels sponsorisés par Google Si vous souhaitez uniquement utiliser des codes promotionnels ou les remises qu'un tiers sponsorise, vous pouvez spécifier votre propre configuration et ignorer cette section.
Google spécifie le type de promotion à sponsoriser et les contacts à définir. configurer l'intégration. Nous fournissons les informations suivantes:
- Montant de la remise.
- Valeur minimale du panier.
- Dates de début et de fin d'utilisation des codes promotionnels.
- Montant maximal du budget alloué à la campagne promotionnelle.
- Le nombre d'utilisations d'un code promotionnel
Exemples de codes promotionnels:
FopaNewUser: 10% (pourcentage fixe) avec une remise maximale de 50 $.FopaMoreThan50: 10 $ (montant fixe de remise).
Vous serez contacté si Google décide d'interrompre l'application du code.
Configurer les paiements
Contactez votre consultant PAA Google pour configurer le processus de versement. Google rembourse uniquement les transactions impliquant des publicités sponsorisées par Google. si l'état final de la commande est l'un des suivants:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implémenter le paiement avec promotions
Cette section décrit comment mettre en œuvre le processus de paiement lorsque vous prenez en charge
codes promotionnels (sponsorisés par Google ou par un tiers). Pour
des remises automatiques sponsorisées par un tiers, il vous suffit de renvoyer la remise
ligne de commande dans la CheckoutResponseMessage (la vérification du code promotionnel n'est pas obligatoire
si nécessaire).
Lors du traitement d'une commande de repas, Google envoie un seul code promotionnel dans le champ
CheckoutRequestMessage à votre traitement. Les utilisateurs peuvent modifier
leur panier ou
code promotionnel lors des demandes de paiement répétées.
Pour vérifier si c'est la première fois que l'utilisateur applique un code promotionnel, procédez comme suit : suivantes:
- Codes promotionnels Google: Google vérifie si un utilisateur connu si vous essayez d'utiliser à nouveau le même code promotionnel ; vous n'avez rien à faire.
- Codes promotionnels tiers ou remises automatiques: si vous avez
n'ont pas été implémentés, vous ne pourrez pas vérifier
les informations de l'utilisateur lors
du traitement de la demande de paiement. Vérifiez plutôt
pendant le traitement de
SubmitOrderRequestMessage, à l'aide deContactdétails (comme l'adresse e-mail de l'utilisateur) à partir duFoodCartExtension. .
Identifiez les erreurs ou les remises sur calcul lors de votre traitement en fonction des dernières demande de paiement. Veillez à ce que votre système ne reste pas obsolète des informations d'état.
Vérifier la validité du code promotionnel
Votre traitement doit vérifier la validité ou l'éligibilité d'une promotion donnée.
selon les conditions spécifiées, telles que la date d'expiration, l'utilisation maximale
de remise maximale. Ensuite, répondez de manière appropriée dans le CheckoutResponseMessage.
avec la remise calculée, ou avec foodOrderErrors si le code promotionnel
ne peuvent pas être appliquées. Si vous détectez des erreurs concernant le code promotionnel, suivez les
décrit dans Gérer les erreurs liées aux promotions.
L'extrait de code suivant présente un exemple de foodOrderErrors pour un code promotionnel.
Assurez-vous que correctedProposedOrder n'inclut pas les promotions.
d'un nœud.
"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 ...}
Remises sur le calcul
Si le code promotionnel est valide, votre traitement doit calculer la remise
et renvoyez un CheckoutResponseMessage avec les valeurs calculées
valeur de remise dans le tableau otherItems. Le prix total de la commande ne doit pas être
négative. Si le montant de la remise dépasse celui du panier, renvoyez le
montant maximal en dollars pour rendre le prix total de la commande à 0 $.
L'extrait suivant montre un exemple de section CheckoutResponseMessage pour
la remise promotionnelle:
"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",
}
]
}
Lancer les promotions inutilisées
Toutes les demandes de paiement ne mènent pas à une demande d'envoi de commande. Si votre traitement met une promotion en attente au moment du règlement, assurez-vous d'avoir mécanisme permettant de lever la suspension si la promotion n'est pas revendiquée via après un certain délai. Cela garantit que votre alimentation de commande maintient le bon quota de campagne.
Gérer les erreurs liées aux promotions
Si votre traitement détermine que le code promotionnel
CheckoutRequestMessage n'est pas valide (par exemple, il a expiré, n'est pas valide,
ou non reconnu), envoyez un CheckoutResponseMessage avec un foodOrderError
contenant le code d'erreur applicable, le texte du motif, ainsi que
Objets correctedProposedOrder et paymentOptions.
Si votre traitement détecte plusieurs erreurs de code promotionnel à partir de la même demande, renvoyer les erreurs irrécupérables avant de renvoyer les erreurs récupérables. Hiérarchisez vos vérifications comme suit (de la priorité la plus élevée à la plus faible):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Exemples
Voici un exemple de demande de paiement avec un code promotionnel:
{ "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 }
Voici la réponse de fulfillment correspondante lors du règlement si la promotion est valide:
{ "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": [] } } }
Voici un exemple de réponse lors du règlement si le code promotionnel n'est pas valide:
{ "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" } } } ] } } }
Implémenter l'envoi de commandes avec promotions
Dans le traitement de votre commande, vérifiez s'il s'agit de la première fois
utilisateur applique un code promotionnel. Pendant SubmitOrderRequestMessage
traitement, vous pouvez vérifier cela à l'aide des détails de Contact (tels que le
l'adresse e-mail de l'utilisateur) à partir de l'objet FoodCartExtension.
Vous devez également vérifier que le code promotionnel s'applique bien:
- Si le code s'applique, confirmez la commande et marquez le bon de réduction comme utilisé.
- Si le code n'est plus applicable:refusez la commande avec le
Erreur
PROMO_NOT_APPLICABLE. Vous pouvez indiquer un motif de refus spécifique en utilisant le même mécanisme que pourFoodOrderUpdateExtension.
Exemples
Voici un exemple de demande d'envoi de commande avec des promotions:
{ "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 }
Voici un exemple de réponse d'envoi de commande correspondante à partir d'un traitement Si le code promotionnel est valide:
{ "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": [] } } }
Voici un exemple de réponse "Envoyer la commande" si le code promotionnel n'est pas valide:
"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." } ] } }