Promosi memberikan cara bagi Anda dan Google untuk mendorong pelanggan untuk mencoba layanan pemesanan makanan dengan harga diskon. Google mendukung integrasi Tindakan Pemesanan End-to-End Anda dengan sistem pengelolaan promosi Anda.
Jenis diskon berikut didukung:
- Kode promosi yang disponsori Google: Kode promosi yang telah diisi otomatis 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 pemesanan makanan Anda tanpa kode promosi.
Apa pun jenis diskonnya, Google akan melakukan panggilan checkout ke pemenuhan pemesanan makanan Anda untuk memverifikasi dan menerapkan diskon.
Sebagai developer layanan pemesanan makanan, Anda perlu melakukan beberapa perubahan pada penerapan untuk menghitung diskon dengan kode promosi yang valid atau mengirim error untuk kode promosi yang tidak valid, mengelola batasan penukaran kode promosi, dan melacak data akuntansi penggantian biaya.
Cara memproses promosi
Untuk menerapkan fulfillment yang mendukung promosi, lakukan hal berikut:
- Siapkan integrasi promosi. (Lewati langkah ini jika Anda tidak menggunakan kode promosi yang disponsori Google.)
- Terapkan checkout dengan promosi.
- Terapkan 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 sendiri dan melewati bagian ini.
Google menentukan jenis promosi yang akan disponsori, dan akan menghubungi Anda untuk menyiapkan integrasi. Kami memberikan detail berikut:
- Jumlah diskon.
- Nilai keranjang minimum.
- Tanggal mulai dan akhir untuk menggunakan kode promosi.
- Jumlah uang maksimum yang dianggarkan untuk kampanye promosi.
- Berapa kali kode promosi dapat digunakan.
Contoh kode promosi:
FopaNewUser: 10% (persen tetap) dengan maksimum diskon $50.FopaMoreThan50: $10 (diskon untuk jumlah tetap).
Jika Google memutuskan untuk menghentikan penerapan kode, Anda akan dihubungi.
Menyiapkan pencairan dana
Hubungi konsultan Google EAP Anda untuk menyiapkan proses pencairan. Google hanya mengganti transaksi yang melibatkan kode promosi yang disponsori Google jika status pesanan akhir adalah salah satu dari yang berikut:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Menerapkan checkout dengan promosi
Bagian ini menjelaskan penerapan pemrosesan checkout jika 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 (pemeriksaan kode promosi
tidak diperlukan).
Selama pemenuhan pesanan makanan, Google mengirimkan satu kode promosi di
CheckoutRequestMessage ke fulfillment Anda. Pengguna dapat mengubah kode keranjang atau
kode promosi pada permintaan checkout berulang.
Untuk memeriksa apakah ini pertama kalinya pengguna menerapkan kode promosi, lakukan hal berikut:
- Kode promosi yang disponsori Google: Google memeriksa apakah pengguna yang kembali mencoba menggunakan kode promosi yang sama lagi; Anda tidak perlu melakukan apa pun.
- Kode promosi atau diskon otomatis yang disponsori pihak ketiga: 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 terhadap 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 dalam artikel 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 ...}
Diskon komputasi
Jika kode promosi valid, fulfillment Anda harus menghitung nilai uang diskon
dan mengirimkan kembali CheckoutResponseMessage dengan nilai diskon
yang dihitung di array otherItems. Total harga pesanan tidak boleh bernilai 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",
}
]
}
Merilis promosi yang tidak digunakan
Tidak semua permintaan checkout mengarah ke permintaan kirim pesanan. Jika fulfillment Anda menahan promosi pada waktu panggilan checkout, pastikan Anda memiliki mekanisme untuk mencabut penangguhan jika promosi tidak diklaim melalui kirim pesanan setelah jangka waktu tertentu. Hal ini memastikan layanan pemesanan makanan Anda mempertahankan kuota kampanye yang benar.
Menangani error pada 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, kirim 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 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 mengirimkan pemenuhan pesanan, periksa apakah ini pertama kalinya
pengguna menerapkan kode promosi atau tidak. Selama pemrosesan SubmitOrderRequestMessage, Anda dapat memeriksanya menggunakan detail Contact (seperti
alamat email pengguna) dari objek FoodCartExtension.
Anda juga harus memeriksa kembali keberlakuan kode promosi:
- Jika kode tersebut berlaku: Konfirmasi pesanan dan tandai kupon yang telah ditukarkan.
- Jika kode sudah tidak 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 pengiriman 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 pengiriman 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."
}
]
}
}