Promosi memberikan cara bagi Anda dan Google untuk memberikan insentif kepada pelanggan untuk mencoba layanan pemesanan makanan Anda dengan harga diskon. Google mendukung integrasi Pesan dengan Tindakan Google dengan sistem pengelolaan promosi Anda.
Jenis diskon berikut ini didukung:
- Kode promosi yang disponsori Google: Kode promosi yang otomatis diisi otomatis oleh Google atau dimasukkan oleh pengguna.
- Kode promosi yang disponsori pihak ketiga: Kode promosi yang dapat dimasukkan pengguna, disediakan oleh layanan pemesanan makanan Anda.
- Diskon otomatis yang disponsori pihak ketiga: Diskon yang otomatis diterapkan oleh layanan pemesanan makanan Anda tanpa kode promosi.
Terlepas dari jenis diskonnya, Google 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 Anda untuk menghitung diskon bagi kode promosi yang valid atau mengirimkan error untuk kode promosi yang tidak valid, mengelola pembatasan penukaran kode promosi, serta 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.
- Terapkan pengajuan pengiriman dengan promosi.
Siapkan integrasi promosi
Bagian ini menjelaskan cara menyiapkan integrasi promosi jika Anda berencana menggunakan kode promosi yang disponsori Google. Jika Anda 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 menyediakan detail berikut:
- Jumlah diskon.
- Nilai keranjang minimum.
- Tanggal mulai dan akhir untuk menggunakan kode promosi.
- Jumlah anggaran maksimum yang dianggarkan untuk kampanye promosi.
- Frekuensi kode promosi dapat digunakan.
Contoh kode promosi:
FopaNewUser: 10% (persentase tetap) dengan diskon maksimum $50.FopaMoreThan50: $10 (jumlah tetap).
Jika Google memutuskan untuk menghentikan penerapan kode, Anda akan dihubungi.
Siapkan pencairan
Hubungi konsultan EAP Google 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
Terapkan checkout dengan promosi
Bagian ini menjelaskan cara menerapkan pemrosesan checkout jika Anda mendukung
kode promosi (yang disponsori Google atau yang disponsori pihak ketiga). Untuk
diskon otomatis yang disponsori pihak ketiga, Anda hanya perlu menampilkan item baris
diskon di CheckoutResponseMessage (tidak diperlukan pemeriksaan kode
promosi).
Selama pemenuhan pesanan makanan, Google 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 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 komputasi diskon dengan fulfillment Anda berdasarkan permintaan checkout terbaru. Saat melakukannya, pastikan sistem Anda tidak menyimpan informasi status yang tidak berlaku.
Periksa validitas kode promosi
fulfillment Anda harus memeriksa validitas atau kelayakan kode promosi
tertentu berdasarkan persyaratan yang telah ditentukan, seperti tanggal habis masa berlaku, penggunaan maksimum, dan
diskon maksimum. Kemudian, berikan respons yang sesuai di CheckoutResponseMessage
dengan diskon yang dihitung, atau dengan foodOrderErrors jika kode promosi
tidak dapat diterapkan. Jika Anda mendeteksi error dengan kode promosi, ikuti proses
yang dijelaskan dalam Menangani error dengan promosi.
Cuplikan berikut menampilkan 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 dolar
diskon dan mengirimkan kembali CheckoutResponseMessage dengan nilai diskon
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 ke $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 pesanan yang dikirim. Jika fulfillment Anda menangguhkan promosi pada waktu panggilan checkout, pastikan Anda memiliki mekanisme yang dapat membatalkan penangguhan jika promosi tidak diklaim melalui pesanan yang dikirim setelah jangka waktu tertentu. Hal ini memastikan layanan pemesanan makanan Anda mempertahankan kuota kampanye yang benar.
Menangani error dengan promosi
Jika fulfillment Anda menentukan bahwa kode promosi dari
CheckoutRequestMessage tidak valid (misalnya, kode sudah tidak berlaku, tidak valid,
atau tidak dikenali), kirim CheckoutResponseMessage dengan foodOrderError
yang berisi kode error dan teks alasan yang berlaku, bersama dengan
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 ini 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 urutan pengiriman dengan promosi
Dalam fulfillment pesanan yang Anda kirimkan, periksa apakah ini adalah 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 kodenya berlaku: Konfirmasi pesanan dan tandai kupon yang telah ditukarkan.
- Jika kode tidak lagi berlaku: Tolak pesanan dengan
error
PROMO_NOT_APPLICABLE. Anda dapat memberikan alasan penolakan tertentu menggunakan mekanisme yang sama sepertiFoodOrderUpdateExtension.
Contoh
Berikut adalah contoh permintaan pengiriman 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 pesanan pengiriman yang sesuai dari suatu 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."
}
]
}
}