توفّر العروض الترويجية لك ولـ Google طريقة لتحفيز العملاء على تجربة خدمة طلب الطعام من خلال تقديم أسعار مخفَّضة. تتيح Google دمج "الإجراءات الشاملة لطلب الشراء" مع نظام إدارة العروض الترويجية.
تتوفّر الأنواع التالية من الخصومات:
- الرموز الترويجية التي تدعمها Google: هي الرموز الترويجية التي تملأها Google تلقائيًا مسبقًا أو يُدخلها المستخدمون.
- الرموز الترويجية التي تقدّمها جهات خارجية: هي رموز ترويجية يمكن للمستخدمين إدخالها، ويقدّمها مقدّم خدمة طلب الطعام.
- الخصومات التلقائية التي تقدّمها جهات خارجية: هي الخصومات التي تطبّقها خدمة طلب الطعام تلقائيًا بدون رمز ترويجي.
بغض النظر عن نوع الخصم، تجري Google مكالمة دفع مع فريق تنفيذ طلبات الطعام للتحقّق من الخصم وتطبيقه.
بصفتك مطوّر خدمة طلب الطعام، عليك إجراء بعض التغييرات على عملية التنفيذ لاحتساب الخصومات لرمزَي الترويجيَين الصالحَين أو إرسال أخطاء لرمزَي الترويجيَين غير الصالحَين، وإدارة حدود تحصيل قيمة رمزَي الترويجيَين ، وتتبُّع بيانات المحاسبة لطلب التعويض.
كيفية معالجة العروض الترويجية
لتنفيذ عملية توصيل تتيح العروض الترويجية، اتّبِع الخطوات التالية:
- إعداد عملية دمج العروض الترويجية (تخطّ هذه الخطوة إذا كنت لا تستخدم الرموز الترويجية التي تدعمها Google).
- تنفيذ ميزة الدفع مع العروض الترويجية
- تنفيذ ميزة إرسال الطلبات مع العروض الترويجية
إعداد عملية دمج العروض الترويجية
يوضّح هذا القسم كيفية إعداد دمج العروض الترويجية إذا كنت تخطّط لاستخدام الرموز الترويجية التي تدعمها Google. إذا كنت تريد فقط السماح بالرموز الترويجية أو الخصومات التي تقدّمها جهة خارجية، يمكنك تحديد الإعداد الخاص بك وتخطّي هذا القسم.
تحدّد Google نوع العرض الترويجي الذي تريد رعايته، وتتواصل معك لإعداد عملية الدمج. نوفّر التفاصيل التالية:
- مبلغ الخصم
- الحد الأدنى لقيمة سلة التسوّق
- تاريخا بدء استخدام الرموز الترويجية وانتهائها
- الحدّ الأقصى للمبلغ المخصّص للميزانية في الحملة الترويجية
- عدد المرات التي يمكن فيها استخدام الرموز الترويجية
أمثلة على الرموز الترويجية:
-
FopaNewUser: 10% (نسبة ثابتة) بحد أقصى 50 دولار أمريكي FopaMoreThan50: 10 ريال سعودي (خصم بقيمة ثابتة)
إذا قرّرت Google إيقاف تطبيق الرمز، سيتم التواصل معك.
إعداد عمليات الصرف
تواصَل مع استشاري EAP في Google لإعداد عملية الدفع. لا تعوض Google المعاملات التي تتضمّن رموًا ترويجيًا ممولة من Google إلا إذا كانت حالة الطلب النهائية هي إحدى الحالات التالية:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
تنفيذ ميزة الدفع باستخدام العروض الترويجية
يوضّح هذا القسم كيفية تنفيذ معالجة الدفع عند إتاحة استخدام
رموز ترويجية (مُعلَن عنها من Google أو من جهة خارجية). بالنسبة إلى
الخصومات التلقائية التي تقدّمها جهات خارجية، ما عليك سوى عرض السطر الخاص بالخصم
في CheckoutResponseMessage (ولا يلزم التحقّق من الرمز الترويجي).
أثناء تسليم طلبات الطعام، ترسل Google رمزًا ترويجيًا واحدًا في ملف
CheckoutRequestMessage إلى جهة التسليم. يمكن للمستخدمين تغيير سلة التسوّق أو
الرمز الترويجي عند تكرار طلبات الدفع.
للتحقّق مما إذا كانت هذه هي المرة الأولى التي يطبّق فيها المستخدم رمزًا ترويجيًا، اتّبِع الخطوات التالية:
- الرموز الترويجية التي تدعمها Google: تتحقّق Google مما إذا كان أحد المستخدِمين المكرّري الزيارة يحاول استخدام الرمز الترويجي نفسه مرّة أخرى، وليس عليك اتّخاذ أي إجراء.
- الرموز الترويجية أو الخصومات التلقائية التي تقدّمها جهات خارجية: إذا لم تكن قد
نفّذت ربط الحساب وموافقة المستخدم، لن تتمكّن من التحقّق من
تفاصيل المستخدم أثناء معالجة طلب الدفع. بدلاً من ذلك، تحقّق من ذلك
أثناء معالجة
SubmitOrderRequestMessage، باستخدام تفاصيلContact(مثل عنوان البريد الإلكتروني للمستخدم) من العنصرFoodCartExtension.
يمكنك تحديد الأخطاء أو احتساب الخصومات من خلال عملية التسليم استنادًا إلى أحدث طلب دفع. عند إجراء ذلك، تأكَّد من أنّ نظامك لا يحتفظ بمعلومات حالة قديمة.
التحقّق من صلاحية الرمز الترويجي
على فريق المعالجة التحقّق من صلاحية رمز ترويجي معيّن أو أهليته وفقًا للأحكام المنصوص عليها، مثل تاريخ انتهاء الصلاحية والحد الأقصى لاستخدامه والحد الأقصى للخصم. بعد ذلك، يجب الردّ بشكل مناسب في الحقل CheckoutResponseMessage
بالخصم المحسوب، أو باستخدام foodOrderErrors إذا تعذّر تطبيق الرمز الترويجي. إذا رصدت أخطاء في الرمز الترويجي، اتّبِع الخطوات описанة في مقالة معالجة الأخطاء في العروض الترويجية.
يعرض المقتطف التالي مثالاً foodOrderErrors على رمز ترويجي.
تأكَّد من أنّ العنصر correctedProposedOrder لا يتضمّن العنصر
promotions.
"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." } ] } }