Promosyonlar, sizin ve Google'ın müşterileri yemek siparişi hizmetinizi indirimli fiyatlarla denemeye teşvik etmesi için bir yol sunar. Google, Order with Google Actions'ın promosyon yönetim sisteminize entegre edilmesini destekler.
Aşağıdaki indirim türleri desteklenir:
- Google sponsorluğunda promosyon kodları: Google tarafından otomatik olarak doldurulan veya kullanıcılar tarafından girilen promosyon kodları.
- Üçüncü taraf sponsorlu promosyon kodları: Kullanıcıların girdiği, yemek siparişi hizmeti tarafından sağlanan promosyon kodlarıdır.
- Üçüncü taraf sponsorlu otomatik indirimler: Yemek siparişi hizmetinizin promosyon kodu olmadan otomatik olarak uyguladığı indirimler.
İndirimin türü ne olursa olsun Google, indirimi doğrulamak ve uygulamak için yemek siparişi karşılama işleminizi gerçekleştirir.
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 kullanma sınırlarını yönetmek ve geri ödeme için muhasebe verilerini izlemek üzere uygulamanızda bazı değişiklikler yapmanız gerekir.
Promosyonlar nasıl işlenir?
Promosyonları destekleyen bir sipariş karşılama işlemi uygulamak için aşağıdakileri yapın:
- Promosyon entegrasyonunu ayarlayın. (Google'ın sponsor olduğu promosyon kodlarını kullanmıyorsanız bu adımı atlayın.)
- Promosyonlarla ödeme işlemini uygulayın.
- Siparişi promosyonlarla birlikte uygulayın.
Promosyon entegrasyonu oluşturun
Bu bölümde, Google sponsorlu promosyon kodlarını kullanmayı planlıyorsanız promosyon entegrasyonunun nasıl ayarlanacağı açıklanmaktadır. Yalnızca bir üçüncü tarafın sponsor olduğu promosyon kodlarını veya indirimleri desteklemek istiyorsanız kendi ayarlarınızı belirtebilir ve bu bölümü atlayabilirsiniz.
Google, sponsorluk yapılacak promosyon türünü belirtir ve entegrasyonu ayarlamak için sizinle iletişime geçer. Aşağıdaki ayrıntıları sağlıyoruz:
- İndirim tutarı.
- Minimum alışveriş sepeti değeri.
- Promosyon kodlarını kullanmaya başlamak için başlangıç ve bitiş tarihi.
- Promosyon kampanyası için harcanan maksimum dolar tutarı.
- Promosyon kodlarının kaç kez kullanılabileceği.
Promosyon kodu örnekleri:
FopaNewUser: Maksimum %50 indirimle %10 (sabit yüzde).FopaMoreThan50: 10 ABD doları (sabit tutar indirimli).
Google, kodun uygulanmasını durdurmaya karar verirse sizinle iletişime geçilir.
Ödemeleri ayarlama
Ödeme işlemini ayarlamak için Google EAP danışmanınızla iletişime geçin. Google, yalnızca son sponsorlu ürün durumunun aşağıdakilerden biri olması durumunda, Google sponsorlu promosyon kodlarını içeren işlemleri geri öder:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Ödemelerinizi promosyonlarla uygulayın
Bu bölümde, promosyon kodlarını (Google sponsorluğunda veya üçüncü taraf sponsorlu) desteklerken ödeme işlemi gerçekleştirme açıklanmaktadır. Üçüncü taraf sponsorlu otomatik indirimlerde yalnızca CheckoutResponseMessage üzerinden indirim satır öğesini iade etmeniz gerekir (promosyon kodu kontrolü gerekmez).
Google, yemek siparişi karşılama sürecinde CheckoutRequestMessage üzerinden karşılamanıza tek bir promosyon kodu gönderir. Kullanıcılar, yinelenen ödeme isteklerinde alışveriş sepetlerini veya promosyon kodlarını değiştirebilir.
Kullanıcının promosyon kodunu ilk kez uygulayıp uygulamadığını kontrol etmek için aşağıdakileri yapın:
- Google sponsorlu promosyon kodları: Google, geri gelen bir 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 ve kullanıcı etkinleştirme işlemlerini gerçekleştirmediyseniz ödeme isteğinin işlenmesi sırasında kullanıcı bilgilerini kontrol edemezsiniz. Bunun yerine
FoodCartExtensionnesnesindekiContactayrıntılarını (kullanıcının e-posta adresi gibi) kullanarakSubmitOrderRequestMessageişlemi sırasında bunu kontrol edin.
En son ödeme isteğine dayalı olarak sipariş karşılama işleminizde hataları tanımlayın veya indirimler hesaplayın. Bunu yaparken, sisteminizin eski durum bilgilerini tutmadığından emin olun.
Promosyon kodu geçerliliğini kontrol edin
Sipariş karşılama işleminiz, belirli bir promosyon kodunun geçerlilik veya uygunluk durumunu, öngörülen şartlar (ör. geçerlilik bitiş tarihi, maksimum kullanım ve maksimum indirim) açısından kontrol etmelidir. Ardından, hesaplanan indirimle CheckoutResponseMessage içinde veya promosyon kodu uygulanamıyorsa foodOrderErrors ile uygun bir şekilde yanıt verin. Promosyon koduyla ilgili hata tespit ederseniz Promosyonlarla ilgili hataları işleme bölümünde açıklanan işlemleri uygulayın.
Aşağıdaki snippet'te bir promosyon kodu için örnek foodOrderErrors gösterilmektedir.
correctedProposedOrder öğesinin promosyon 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 ...}
İşlem indirimleri
Promosyon kodu geçerliyse karşılama işleminiz, indirim tutarı değerini hesaplamalı ve otherItems dizisinde hesaplanan indirim değerini içeren bir CheckoutResponseMessage 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 çıkarmak için maksimum dolar tutarını 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ı iptal etme
Her ödeme isteği, bir sipariş gönderme isteğiyle sonuçlanmaz. Sipariş karşılama için ödeme sırasında bir promosyonda bekletme söz konusuysa promosyon belirli bir süre sonra talep edilmediği takdirde bekletmeyi iptal etmek için kullanabileceğiniz bir mekanizmanız olduğundan emin olun. Bu şekilde, yemek siparişi hizmetinizin doğru kampanya kotasını korumasını sağlarsınız.
Promosyonlarla ilgili hataları giderme
Talebiniz bir CheckoutRequestMessage promosyon kodunun geçerli olmadığını belirlerse (örneğin, süresi dolmuş, geçersiz veya tanınmadıysa) geçerli hata kodu ve neden metnini correctedProposedOrder ve paymentOptions nesneleriyle birlikte içeren bir foodOrderError içeren CheckoutResponseMessage gönderin.
İstek karşılamada aynı istekten birden fazla promosyon kodu hatası bulunursa kurtarılabilir hataları geri göndermeden önce kurtarılamayan hataları geri gönderin. Kontrollerinizi aşağıdaki gibi önceliklendirin (yüksekten yükseğe doğru):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Örnekler
Promosyon kodu içeren ödeme isteği örneğini aşağıda bulabilirsiniz:
{
"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 istek karşılamayla ilgili ödeme yanıtını aşağıda bulabilirsiniz:
{
"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 kodu geçersizse ö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"
}
}
}
]
}
}
}
Gönderim talebini promosyonlarla uygulama
Sipariş gönderme karşılamanızda, kullanıcının ilk kez bir promosyon kodu uygulayıp uygulamadığını kontrol edin. SubmitOrderRequestMessage işlemi sırasında, FoodCartExtension nesnesindeki Contact ayrıntılarını (kullanıcının e-posta adresi gibi) kullanarak bunu kontrol edebilirsiniz.
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ı olan siparişi reddedin.FoodOrderUpdateExtensionile aynı mekanizmayı kullanarak belirli bir reddedilme nedeni belirtebilirsiniz.
Örnekler
Promosyon içeren bir sipariş isteği örneği aşağıda verilmiştir:
{
"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 bir sipariş karşılamaya karşılık gelen sipariş gönderme yanıtı örneğini burada bulabilirsiniz:
{
"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ş gönderme yanıtı örneğini aşağıda 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."
}
]
}
}