Promosi memberikan cara bagi Anda dan Google untuk memberikan insentif kepada pelanggan agar mencoba layanan pemesanan makanan Anda dengan harga diskon. Google mendukung integrasi Tindakan Pemesanan Lengkap dengan sistem pengelolaan promosi Anda.
Jenis diskon berikut didukung:
- Kode promosi yang disponsori Google: Kode promosi yang otomatis diisi sebelumnya oleh Google atau dimasukkan oleh pengguna.
- Kode promosi yang disponsori pihak ketiga: Kode promosi yang dapat dimasukkan pengguna, yang disediakan oleh layanan pemesanan makanan Anda.
- Diskon otomatis yang disponsori pihak ketiga: Diskon yang otomatis diterapkan oleh layanan pesan makanan Anda tanpa kode promosi.
Terlepas dari jenis diskon, Google melakukan panggilan checkout ke fulfillment pemesanan makanan Anda untuk memverifikasi dan menerapkan diskon.
Sebagai developer layanan pemesanan makanan, Anda perlu melakukan beberapa perubahan pada penerapan untuk menghitung diskon untuk kode promosi yang valid atau mengirim error untuk kode promosi yang tidak valid, mengelola batasan penukaran kode promosi, dan melacak data akuntansi untuk penggantian biaya.
Cara memproses promosi
Untuk menerapkan fulfillment yang mendukung promosi, lakukan hal berikut:
- Menyiapkan integrasi promosi. (Lewati langkah ini jika Anda tidak menggunakan kode promosi yang disponsori Google.)
- Terapkan checkout dengan promosi.
- Menerapkan pengiriman pesanan dengan promosi.
Menyiapkan integrasi promosi
Bagian ini menjelaskan cara menyiapkan integrasi promosi jika Anda berencana menggunakan kode promosi yang disponsori Google. Jika hanya ingin mendukung kode promosi atau diskon yang disponsori pihak ketiga, Anda dapat menentukan penyiapan Anda sendiri dan melewati bagian ini.
Google menentukan jenis promosi yang akan disponsori, dan menghubungi Anda untuk menyiapkan integrasi. Kami memberikan detail berikut:
- Jumlah diskon.
- Nilai keranjang minimum.
- Tanggal mulai dan akhir untuk menggunakan kode promosi.
- Jumlah dolar maksimum yang dianggarkan untuk kampanye promosi.
- Frekuensi penggunaan kode promosi.
Contoh kode promosi:
FopaNewUser: 10% (persentase tetap) dengan diskon maksimum $50.FopaMoreThan50: $10 (diskon jumlah tetap).
Jika Google memutuskan untuk menghentikan penerapan kode, Anda akan dihubungi.
Menyiapkan pencairan dana
Hubungi konsultan Google EAP Anda untuk menyiapkan proses pencairan dana. Google hanya mengganti biaya transaksi yang melibatkan kode promosi yang disponsori Google jika status pesanan akhir adalah salah satu dari berikut:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Menerapkan checkout dengan promosi
Bagian ini menjelaskan penerapan pemrosesan checkout saat Anda mendukung
kode promosi (disponsori Google atau pihak ketiga). Untuk
diskon otomatis yang disponsori pihak ketiga, Anda hanya perlu menampilkan item baris
diskon di CheckoutResponseMessage (tidak diperlukan pemeriksaan kode promosi).
Selama fulfillment pesanan makanan, Google akan mengirimkan satu kode promosi di
CheckoutRequestMessage ke fulfillment Anda. Pengguna dapat mengubah keranjang atau
kode promosi mereka pada permintaan checkout berulang.
Untuk memeriksa apakah ini pertama kalinya pengguna menerapkan kode promosi, lakukan hal berikut:
- Kode promosi yang disponsori Google: Google akan memeriksa apakah pengguna yang kembali mencoba menggunakan kode promosi yang sama lagi; Anda tidak perlu melakukan apa pun.
- Kode promosi yang disponsori pihak ketiga atau diskon otomatis: Jika belum
menerapkan penautan akun dan keikutsertaan pengguna, Anda tidak akan dapat memeriksa
detail pengguna selama pemrosesan permintaan checkout. Sebagai gantinya, periksa hal ini
selama pemrosesan
SubmitOrderRequestMessage, menggunakan detailContact(seperti alamat email pengguna) dari objekFoodCartExtension.
Identifikasi error atau hitung diskon dengan fulfillment Anda berdasarkan permintaan checkout terbaru. Saat melakukannya, pastikan sistem Anda tidak menyimpan informasi status yang sudah tidak berlaku.
Memeriksa validitas kode promosi
Fulfillment Anda harus memeriksa validitas atau kelayakan kode promosi
tertentu berdasarkan persyaratan yang ditetapkan, seperti tanggal habis masa berlaku, penggunaan maksimum, dan
diskon maksimum. Kemudian, respons dengan tepat di CheckoutResponseMessage
dengan diskon yang dihitung, atau dengan foodOrderErrors jika kode promosi
tidak dapat diterapkan. Jika Anda mendeteksi error pada kode promosi, ikuti
proses yang dijelaskan di Menangani error pada promosi.
Cuplikan berikut menunjukkan contoh foodOrderErrors untuk kode promosi.
Pastikan correctedProposedOrder tidak menyertakan node promosi.
"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 ...}
Menghitung diskon
Jika kode promosi valid, fulfillment Anda harus menghitung nilai dolar
diskon dan mengirim kembali CheckoutResponseMessage dengan nilai discount
yang dihitung dalam array otherItems. Total harga pesanan tidak boleh
negatif. Jika jumlah diskon melebihi jumlah keranjang, kirim kembali
jumlah dolar maksimum untuk merender total harga pesanan menjadi $0.
Cuplikan berikut menunjukkan contoh bagian CheckoutResponseMessage untuk
diskon promosi:
"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",
}
]
}
Melepaskan promosi yang tidak digunakan
Tidak semua permintaan checkout menghasilkan permintaan kirim pesanan. Jika fulfillment Anda menahan promosi pada waktu panggilan checkout, pastikan Anda memiliki mekanisme untuk melepaskan penangguhan jika promosi tidak diklaim melalui pengiriman pesanan setelah jangka waktu tertentu. Hal ini memastikan bahwa layanan pesan makanan Anda mempertahankan kuota kampanye yang benar.
Menangani error dengan promosi
Jika fulfillment Anda menentukan bahwa kode promosi dari
CheckoutRequestMessage tidak valid (misalnya, sudah tidak berlaku, tidak valid,
atau tidak dikenali), kirim CheckoutResponseMessage dengan foodOrderError
yang berisi kode error dan teks alasan yang berlaku, beserta
objek correctedProposedOrder dan paymentOptions.
Jika fulfillment Anda menemukan beberapa error kode promosi dari permintaan yang sama, kirimkan kembali error yang tidak dapat dipulihkan sebelum mengirim kembali error yang dapat dipulihkan. Prioritaskan pemeriksaan Anda sebagai berikut (dari prioritas tinggi ke rendah):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Contoh
Berikut adalah contoh permintaan checkout dengan kode promosi:
{ "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 }
Berikut adalah respons checkout yang sesuai dari fulfillment jika kode promosi valid:
{ "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": [] } } }
Berikut adalah contoh respons checkout jika kode promosi tidak valid:
{ "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" } } } ] } } }
Menerapkan kirim pesanan dengan promosi
Dalam fulfillment pesanan yang dikirimkan, periksa apakah ini pertama kalinya
pengguna menerapkan kode promosi. Selama pemrosesan SubmitOrderRequestMessage, Anda dapat memeriksanya menggunakan detail Contact (seperti alamat email pengguna) dari objek FoodCartExtension.
Anda juga harus memeriksa kembali penerapan kode promosi:
- Jika kode berlaku: Konfirmasi pesanan dan tandai kupon yang ditukarkan.
- Jika kode tidak lagi berlaku: Tolak pesanan dengan
error
PROMO_NOT_APPLICABLE. Anda dapat memberikan alasan penolakan tertentu menggunakan mekanisme yang sama seperti untukFoodOrderUpdateExtension.
Contoh
Berikut adalah contoh permintaan kirim pesanan dengan promosi:
{ "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 }
Berikut adalah contoh respons kirim pesanan yang sesuai dari fulfillment jika kode promosi valid:
{ "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": [] } } }
Berikut adalah contoh respons kirim pesanan jika kode promosi tidak valid:
"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." } ] } }