توفر العروض الترويجية لك ول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."
}
]
}
}