وتوفّر العروض الترويجية طريقة لك وGoogle لتحفيز العملاء على تجربة خدمة طلب الطعام بأسعار مخفَّضة. تتيح Google دمج طلبك مع "المهام مع Google" مع نظام إدارة العروض الترويجية.
تتوفّر الأنواع التالية من الخصومات:
- الرموز الترويجية التي ترعاها Google: هي رموز ترويجية يتم ملؤها تلقائيًا بواسطة Google أو يدخلها المستخدمون.
- الرموز الترويجية التي تقدّمها جهات خارجية: الرموز الترويجية التي يمكن للمستخدمين الدخول إليها والتي تقدّمها خدمة طلب الطعام
- خصومات تلقائية تقدّمها جهات خارجية: هي الخصومات التي يتم تطبيقها تلقائيًا على خدمة طلب الطعام بدون رمز ترويجي.
وبغض النظر عن نوع الخصم، تُجري Google مكالمة دفع إلى الحساب عند طلب الطعام للتحقق من الخصم وتطبيقه.
بصفتك مطوّرًا لخدمة طلب الطعام، عليك إجراء بعض التغييرات على عملية التنفيذ لاحتساب الخصومات على الرموز الترويجية الصالحة أو إرسال أخطاء للرموز الترويجية غير الصالحة، وإدارة القيود المفروضة على تحصيل قيمة الرمز الترويجي، وتتبُّع بيانات المحاسبة من أجل التعويض.
كيفية معالجة العروض الترويجية
لتنفيذ عملية توصيل تتيح العروض الترويجية، اتّبِع الخطوات التالية:
- إعداد دمج العروض الترويجية: (تخطّي هذه الخطوة إذا كنت لا تستخدم الرموز الترويجية التي ترعاها Google).
- نفِّذ عملية الدفع باستخدام العروض الترويجية.
- نفِّذ طلب الشراء باستخدام العروض الترويجية.
إعداد عملية دمج العروض الترويجية
يوضّح هذا القسم كيفية إعداد عملية دمج العروض الترويجية إذا كنت تنوي استخدام الرموز الترويجية التي ترعاها Google. إذا كان المطلوب إتاحة الرموز الترويجية أو الخصومات التي يقدّمها طرف ثالث فقط، يمكنك تحديد الإعداد الخاص بك وتخطّي هذا القسم.
تحدّد Google نوع العرض الترويجي الذي تريده، وتتواصل معك لإعداد عملية الدمج. في ما يلي التفاصيل التالية:
- مبلغ الخصم.
- تمثّل هذه السمة الحد الأدنى لقيمة سلة التسوّق.
- تاريخا البدء والانتهاء لاستخدام الرموز الترويجية.
- الحد الأقصى للمبلغ بالدولار المحدَّد للميزانية للحملة الترويجية.
- عدد المرات التي يمكن فيها استخدام الرموز الترويجية
أمثلة على الرموز الترويجية:
FopaNewUser: %10 (نسبة مئوية ثابتة) مع خصم بقيمة %50 كحد أقصىFopaMoreThan50: 10 دولار أمريكي (خصم ثابت)
وفي حال قررت Google تعليق تطبيق الرمز، سيتم التواصل معك.
إعداد الدفعات
تواصَل مع مستشار Google التابع لك في ما يتعلق ببروتوكول EAP لإعداد عملية الدفع. لا تدفع Google سوى المعاملات التي تتضمن رموزًا ترويجية ترويجية مقدَّمة من Google إذا كانت حالة الطلب النهائي هي إحدى الحالات التالية:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
تنفيذ عملية الدفع باستخدام العروض الترويجية
يصف هذا القسم تنفيذ معالجة الدفع عند إتاحة
الرموز الترويجية (برعاية Google أو برعاية جهة خارجية). بالنسبة إلى الخصومات التلقائية التي توفّرها جهة خارجية، ما عليك سوى إرجاع عنصر الخصم في CheckoutResponseMessage (لا حاجة إلى التحقق من الرمز الترويجي).
أثناء توصيل الطعام، ترسل Google رمزًا ترويجيًا واحدًا في CheckoutRequestMessage إلى توصيل الطلب. يمكن للمستخدمين تغيير سلة التسوق أو الرمز الترويجي في طلبات الدفع المتكررة.
للتحقّق مما إذا كانت هذه هي المرة الأولى التي يطبِّق فيها المستخدم رمزًا ترويجيًا، اتّبِع الخطوات التالية:
- الرموز الترويجية التي تروّج لها Google: تتحقّق Google مما إذا كان المستخدم المكرّر يحاول استخدام الرمز الترويجي نفسه مرة أخرى، وليس عليك اتخاذ أي إجراء.
- رموز ترويجية تابعة لأطراف ثالثة أو خصومات تلقائية: إذا لم يسبق لك تنفيذ ربط الحساب وموافقة المستخدم، لن تتمكّن من الاطّلاع على تفاصيل المستخدم أثناء معالجة طلب الدفع. يمكنك بدلاً من ذلك التحقّق من ذلك أثناء معالجة
SubmitOrderRequestMessage، وذلك باستخدام تفاصيلContact(مثل عنوان البريد الإلكتروني للمستخدم) من الكائنFoodCartExtension.
حدِّد الأخطاء أو استفِد من الخصومات عند تنفيذ الطلب استنادًا إلى أحدث طلب دفع. أثناء إجراء ذلك، تأكد من أن نظامك لا يحافظ على معلومات الحالة القديمة.
التحقّق من صلاحية الرمز الترويجي
ويجب أن تتحقّق عملية توصيل الطلب من صلاحية أو أهلية رمز ترويجي معيّن استنادًا إلى الأحكام المحدّدة، مثل تاريخ انتهاء الصلاحية والحدّ الأقصى للاستخدام والحدّ الأقصى للخصم. بعد ذلك، يجب الردّ بشكل مناسب في CheckoutResponseMessage
مع خصم محسوب، أو باستخدام foodOrderErrors إذا تعذّر تطبيق الرمز الترويجي. إذا رصدت أخطاء في الرمز الترويجي، اتّبِع العملية الواردة في القسم معالجة الأخطاء المتعلّقة بالعروض الترويجية.
يعرض المقتطف التالي مثالاً على foodOrderErrors لرمز ترويجي.
تأكَّد من أنّ السمة correctedProposedOrder لا تتضمن العروض الترويجية.
"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 ...}
خصومات الحوسبة
وإذا كان الرمز الترويجي صالحًا، يجب أن تحتسب قيمة الخصم قيمة الدولار ويتم إرسال CheckoutResponseMessage مع خصم محسوب في مصفوفة otherItems. يجب ألا يكون إجمالي سعر الطلب سالبًا. وإذا كان مبلغ الخصم يتجاوز مبلغ سلة التسوّق، أرسِل
الحد الأقصى للمبلغ بالدولار الأمريكي لعرض السعر الإجمالي للطلب إلى 0 دولار أمريكي.
يعرض المقتطف التالي مثالاً على قسم CheckoutResponseMessage للخصم الترويجي:
"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",
}
]
}
إصدار العروض الترويجية غير المستخدمة
لا يؤدي كل طلب دفع إلى إرسال طلب. إذا علّقت عملية توصيل الطلب عرضًا ترويجيًا في وقت إجراء عملية الدفع، تأكَّد من استخدام آلية لإلغاء التعليق في حال عدم المطالبة بالعرض الترويجي من خلال إرسال الطلب بعد فترة زمنية معيّنة. ويضمن ذلك احتفاظ خدمة طلب الطعام بالحصة الصحيحة للحملة.
التعامل مع الأخطاء المتعلّقة بالعروض الترويجية
إذا تبيّن بطريقة التنفيذ أنّ الرمز الترويجي من CheckoutRequestMessage غير صالح (على سبيل المثال، أنه منتهي الصلاحية أو غير صالح أو لم يتم التعرّف عليه)، أرسِل CheckoutResponseMessage مع foodOrderError لأنّه يتضمّن رمز الخطأ الساري ونص السبب، فضلاً عن correctedProposedOrder وpaymentOptions كائنَين.
إذا عثرت على طلبات متعددة متعلّقة برمز ترويجي من الطلب نفسه، أرسِل الأخطاء التي لا يمكن استردادها قبل إرسال الأخطاء القابلة للاسترداد. يجب منح الأولوية لعمليات التحقّق على النحو التالي (من الأولوية العالية إلى المنخفضة):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
أمثلة
في ما يلي مثال على طلب الدفع الذي يتضمّن رمزًا ترويجيًا:
{
"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
}
إليك الاستجابة المناسبة لعملية الدفع من طريقة توفُّر الرمز إذا كان الرمز الترويجي صالحًا:
{
"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": []
}
}
}
في ما يلي مثال على الردّ على عملية الدفع إذا كان الرمز الترويجي غير صالح:
{
"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"
}
}
}
]
}
}
}
تنفيذ طلب الإرسال مع العروض الترويجية
تحقَّق مما إذا كانت هذه هي المرة الأولى التي يُطبِّق فيها المستخدم الرمز الترويجي في عملية تنفيذ طلب الإرسال. أثناء معالجة SubmitOrderRequestMessage، يمكنك التحقق من ذلك باستخدام تفاصيل Contact (مثل عنوان البريد الإلكتروني للمستخدم) من الكائن FoodCartExtension.
عليك أيضًا إعادة التحقق من إمكانية تطبيق الرمز الترويجي:
- إذا كان الرمز ساريًا: أكِّد الطلب وضَع علامة على القسيمة تم استخدامها.
- إذا لم يعُد الرمز ساريًا: ارفض الطلب الذي يتضمّن الخطأ
PROMO_NOT_APPLICABLE. يمكنك تقديم سبب رفض محدد باستخدام الآلية نفسها المستخدَمة فيFoodOrderUpdateExtension.
أمثلة
إليك مثال على طلب إرسال يتضمّن عروضًا ترويجية:
{
"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
}
في ما يلي مثال على استجابة طلب الإرسال المقابلة من طريقة التنفيذ إذا كان الرمز الترويجي صالحًا:
{
"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": []
}
}
}
في ما يلي مثال على الردّ على طلب الإرسال إذا كان الرمز الترويجي غير صالح:
"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."
}
]
}
}