Promosyonlar, sizin ve Google'ın müşterileri indirimli fiyatla yemek siparişi hizmetinizi denemeye teşvik etmesini sağlar. Google, Sipariş Verme Uçtan Uca İşlemlerinizi promosyon yönetim sisteminizle entegre etmeyi destekler.
Aşağıdaki indirim türleri desteklenir:
- Google sponsorlu promosyon kodları: Google tarafından otomatik olarak önceden doldurulmuş veya kullanıcılar tarafından girilen promosyon kodlarıdır.
- Üçüncü taraf sponsorlu promosyon kodları: Yemek siparişi hizmetiniz tarafından sağlanan, kullanıcıların girebileceği promosyon kodları.
- Üçüncü taraf sponsorlu otomatik indirimler: Yemek siparişi hizmetinizin promosyon kodu olmadan otomatik olarak uygulanabileceği indirimlerdir.
Google, indirimin türünden bağımsız olarak indirimi doğrulamak ve uygulamak için yemek siparişi karşılama hizmetinize bir ödeme çağrısı yapar.
Bir yemek siparişi hizmetinin geliştiricisi olarak, geçerli promosyon kodları için indirimleri hesaplamak veya geçersiz promosyon kodlarıyla ilgili hatalar göndermek, promosyon kodu kullanımıyla ilgili sınırlamaları yönetmek ve geri ödeme için muhasebe verilerini izlemek amacıyla uygulamanızda bazı değişiklikler yapmanız gerekir.
Promosyonları işleme
Promosyonları destekleyen bir sipariş karşılama uygulamak için aşağıdakileri yapın:
- Promosyon entegrasyonunu ayarlayın. (Google sponsorlu promosyon kodları kullanmıyorsanız bu adımı atlayın.)
- Promosyonlarda ödeme özelliğini kullanın.
- Promosyonlarla sipariş gönderme.
Promosyon entegrasyonunu ayarlayın
Bu bölümde, Google sponsorluğundaki promosyon kodlarını kullanmayı planlıyorsanız promosyon entegrasyonunu nasıl ayarlayacağınız açıklanmaktadır. Yalnızca üçüncü bir tarafın sponsor olduğu promosyon kodlarını veya indirimleri desteklemek istiyorsanız kendi kurulumunuzu belirleyebilir ve bu bölümü atlayabilirsiniz.
Google, sponsor olacak promosyon türünü belirtir ve entegrasyonu ayarlamanız için sizinle iletişime geçer. Aşağıdaki bilgileri sağlarız:
- İndirim tutarı.
- Minimum alışveriş sepeti değeri.
- Promosyon kodlarının kullanılacağı başlangıç ve bitiş tarihleri.
- Tanıtım kampanyası için bütçelenen maksimum dolar tutarı.
- Promosyon kodlarının kullanım sayısı.
Promosyon kodu örnekleri:
FopaNewUser: Maksimum 50 ABD doları indirimle %10 (sabit yüzde).FopaMoreThan50: 10 TL (sabit tutarda indirim).
Google, kod uygulamasını durdurmaya karar verirse sizinle iletişime geçilecektir.
Ödemeleri ayarla
Ödeme sürecini ayarlamak için Google EAP danışmanınızla iletişime geçin. Google, yalnızca son sipariş durumu aşağıdakilerden biriyse Google sponsorlu promosyon kodlarını içeren işlemler için geri ödeme yapar:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Ödemeleri promosyonlarla uygulayın
Bu bölümde, promosyon kodlarını (Google sponsorluğunda veya üçüncü taraf sponsorlu) desteklerken ödeme işleminin nasıl uygulanacağı açıklanmaktadır. Üçüncü taraf sponsorlu otomatik indirimler için indirim satır öğesini yalnızca CheckoutResponseMessage içinde döndürmeniz gerekir (promosyon kodunun kontrol edilmesi gerekmez).
Google, yemek siparişi karşılama sırasında sipariş karşılama mantığınıza tek bir promosyon kodu CheckoutRequestMessage gönderir. Kullanıcılar, yinelenen ödeme isteklerinde alışveriş sepetlerini veya promosyon kodlarını değiştirebilir.
Kullanıcının ilk kez bir promosyon kodu uygulayıp uygulamadığını kontrol etmek için aşağıdakileri yapın:
- Google sponsorlu promosyon kodları: Google, geri gelen kullanıcının aynı promosyon kodunu tekrar kullanmaya çalışıp çalışmadığını kontrol eder; herhangi bir işlem yapmanız gerekmez.
- Üçüncü taraf sponsorlu promosyon kodları veya otomatik indirimler: Hesap bağlama veya kullanıcı etkinleştirmesi uygulamadıysanız ödeme isteği işlenirken kullanıcının bilgilerini kontrol edemezsiniz. Bunun yerine,
SubmitOrderRequestMessageişlemi sırasındaFoodCartExtensionnesnesindekiContactayrıntılarını (kullanıcının e-posta adresi gibi) kullanarak bunu kontrol edin.
En son ödeme isteğine göre sipariş karşılama işleminizdeki hataları belirleyin veya indirimleri hesaplayın. Bunu yaparken, sisteminizin eski durum bilgilerini tutmadığından emin olun.
Promosyon kodunun geçerliliğini kontrol edin
Sipariş karşılama işleminiz; belirli bir promosyon kodunun geçerliliğini veya uygunluğunu belirli şartlarla (ör. son kullanma tarihi, maksimum kullanım ve maksimum indirim) karşılaştırarak kontrol etmelidir. Ardından, CheckoutResponseMessage içinde hesaplanan indirimle veya promosyon kodu uygulanamıyorsa foodOrderErrors ile uygun şekilde yanıt verin. Promosyon koduyla ilgili hatalar tespit ederseniz Promosyonlarla ilgili hataları giderme bölümünde açıklanan süreci uygulayın.
Aşağıdaki snippet'te promosyon kodu için bir örnek foodOrderErrors gösterilmektedir.
correctedProposedOrder öğesinin tanıtım düğümünü içermediğinden emin olun.
"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 ...}
İndirimleri hesaplayın
Promosyon kodu geçerliyse sipariş karşılama işleminiz, indirimin dolar değerini hesaplamalı ve otherItems dizisindeki hesaplanan indirim değeriyle bir CheckoutResponseMessage geri göndermelidir. Toplam sipariş fiyatı negatif olmamalıdır. İndirim tutarı alışveriş sepeti tutarını aşıyorsa toplam sipariş fiyatını 0 ABD dolarına dönüştürmek için maksimum tutarı geri gönderin.
Aşağıdaki snippet'te promosyon indirimi için örnek bir CheckoutResponseMessage bölümü gösterilmektedir:
"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",
}
]
}
Kullanılmayan promosyonları serbest bırakın
Her ödeme isteği, sipariş isteğiyle sonuçlanmaz. Sipariş karşılama işleminiz, ödeme araması sırasında bir promosyonu bekletmeye neden oluyorsa belirli bir süre sonra sipariş göndererek promosyon için talepte bulunulmaması durumunda bekletmeyi kaldırabileceğiniz bir mekanizmanızın olduğundan emin olun. Bu, yemek siparişi hizmetinizin doğru kampanya kotasını korumasını sağlar.
Promosyonlarla ilgili hataları giderme
Sipariş karşılama işleminiz sonucunda bir CheckoutRequestMessage promosyon kodunun geçerli olmadığını (ör. süresinin dolmuş, geçersiz veya tanınmadığını) tespit ederseniz correctedProposedOrder ve paymentOptions nesneleriyle birlikte geçerli hata kodunu ve neden metnini içeren foodOrderError içeren bir CheckoutResponseMessage gönderin.
Sipariş karşılama işleminiz aynı istekte birden fazla promosyon kodu hatası bulursa kurtarılabilir hataları geri göndermeden önce düzeltilemeyen hataları tekrar gönderin. Kontrollerinizi aşağıdaki şekilde önceliklendirin (yüksek öncelikliden düşük öncelikliye):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Örnekler
Aşağıda promosyon kodu içeren ödeme isteği örneği verilmiştir:
{
"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
}
Promosyon kodu geçerliyse sipariş karşılama mesajının ilgili ödeme yanıtı aşağıda verilmiştir:
{
"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": []
}
}
}
Promosyon kodunun geçersiz olması durumunda gösterilecek bir ödeme yanıtı örneği aşağıda verilmiştir:
{
"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"
}
}
}
]
}
}
}
Promosyonlarla sipariş gönderme işlemini uygulayın
Siparişinizi yerine getirirken, bunun kullanıcının promosyon kodunu ilk kez kullanıp kullanmadığını kontrol edin. SubmitOrderRequestMessage işleme sırasında bunu, FoodCartExtension nesnesindeki Contact ayrıntılarını (kullanıcının e-posta adresi gibi) kullanarak kontrol edebilirsiniz.
Ayrıca, promosyon kodunun geçerliliğini de yeniden kontrol etmeniz gerekir:
- Kod geçerliyse: Siparişi onaylayın ve kuponu kullanıldı olarak işaretleyin.
- Kod artık geçerli değilse:
PROMO_NOT_APPLICABLEhatası içeren siparişi reddedin.FoodOrderUpdateExtensionile aynı mekanizmayı kullanarak belirli bir reddedilme nedeni belirtebilirsiniz.
Örnekler
Promosyonlarla birlikte sipariş isteği gönderme örneği:
{
"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
}
Promosyon kodu geçerliyse sipariş karşılama işlemiyle ilgili sipariş gönderme yanıtının bir örneğini aşağıda görebilirsiniz:
{
"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": []
}
}
}
Promosyon kodu geçersizse sipariş yanıtı göndermeyle ilgili bir örneği burada bulabilirsiniz:
"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."
}
]
}
}