یکپارچه‌سازی فید پیشنهاد ویژه

پیشنهادها

ادغام پیشنهادها به شما امکان می‌دهد اطلاعات ساختاریافته درباره تبلیغات و تخفیف‌های فروشنده را که در زمان‌های خاصی برای خدمات خاصی اعمال می‌شود، منتقل کنید. پیشنهادها از پیشنهاد واقعی (درصد تخفیف، مقدار تخفیف ...)، بازه‌های زمانی اعتبار (زمان‌های خاص، روزهای هفته ...)، و موارد استفاده قابل‌اعمال (پیشنهاد فقط می‌تواند در سرویس‌های خاصی استفاده شود) و همچنین ترکیب‌های پیچیده‌ای از محدودیت‌ها تشکیل شده‌اند.

نمونه‌های پیشنهاد:

• پیش‌غذاها در چهارشنبه‌ها و پنج‌شنبه‌های ماه دسامبر از ۱۲ ظهر تا ۵ عصر با ۵۰٪ تخفیف
• یکی بخر یکی رایگان بگیر برای دسر شام روز مادر از ساعت ۶ تا ۱۰ بعدازظهر
• ‫۵ دلار تخفیف برای غذای اصلی صبحانه-ناهار هر یکشنبه از ساعت ۱۰ صبح تا ۲ بعدازظهر
• ‫٪۱۰ تخفیف به‌عنوان پیشنهاد ویژه حضوری که با ‎٪۵ تخفیف برای مشترکین Premium و ‫‎٪۵ تخفیف درصورت پرداخت کاربر ازطریق برنامه شما قابل ترکیب است.

برای اینکه پیشنهادی در ادغام گنجانده شود، باید با مدل داده‌های فنی مطابقت داشته باشد و الزامات واجدشرایط بودن ما را نیز برآورده کند. حتماً خط‌مشی‌های پیشنهادهای ویژه ما را بررسی کنید تا مطمئن شوید یکپارچه‌سازی شما با آن‌ها مطابقت دارد و دستورالعمل‌های مربوط به نحوه برخورد با پیشنهادهای ویژه‌ای که با الزامات فنی مطابقت ندارند را دریافت کنید.

پیاده‌سازی ارائه می‌دهد

ادغام پیشنهادهای ویژه از دو فید تشکیل شده است که روزانه یا با تناوبی که دقت بالا را تضمین کند (یعنی کهنگی را کاهش دهد) بارگذاری می‌شوند:

• یکی از این دو:
  • فید فروشندگان (بااستفاده از پیکربندی Merchant)
  • یا فید نهاد (بااستفاده از پیکربندی Generic )
• و فید پیشنهادهای ویژه (بااستفاده از پیکربندی Generic )

نام فیلد	نوع	الزام	شرح
data	آرایه شیء (Offer)

نام فیلد	نوع	الزام	شرح
offer_id	رشته	الزامی	شناسه یکتای پیشنهاد ویژه. الزامی.
entity_ids	آرایه رشته		فهرست فروشندگانی که در این پیشنهاد ویژه شرکت می‌کنند.
add_on_offer_applicable_to_all_entities	بولی		اگر درست باشد، این پیشنهاد ویژه برای همه نهادهای تحت مدیریت تجمیع‌کننده قابل اعمال است. فقط برای پیشنهادهای ویژه برافزایی قابل‌اعمال است.
offer_source	enum (OfferSource)	الزامی	پیشنهاد می‌تواند توسط تجمیع‌کننده، فروشنده مستقل، یا حتی شخص ثالث به‌عنوان برافزا ارائه شود. الزامی.
action_type	شمارشی (ActionType)	الزامی	سرویسی که پیشنهاد را ارائه می‌کند. هر offer_id فقط می‌تواند به یک action_type تعلق داشته باشد. اگر پیشنهادی را بتوان در چندین نوع خدمات هم‌رسانی کرد، انتظار می‌رود پیشنهادهای تکراری با شناسه‌های یکتا برای هر نوع خدمات ایجاد شود. الزامی.
offer_modes	آرایه شمارشی (OfferMode)	الزامی	روش‌هایی که پیشنهاد ویژه می‌تواند دردسترس قرار گیرد - مراجعه حضوری، رزرو، آنلاین، و غیره. الزامی است.
offer_category	شمارشی (OfferCategory)	الزامی	دسته پیشنهاد. الزامی.
source_assigned_priority	شماره		عدد صحیح غیرمنفی ([۱-۱۰۰]، که در آن ۱ نشان‌دهنده بالاترین اولویت است) نشان‌دهنده سطح اولویت پیشنهاد ویژه اختصاص‌داده‌شده توسط منبع. وقتی چندین پیشنهاد ویژه برای یک فروشنده دردسترس باشد، این سیگنالی برای رتبه‌بندی پیشنهادهای ویژه خواهد بود. 0 نشان‌دهنده این است که اولویت تنظیم نشده است.
offer_details	شیء (OfferDetails)	الزامی	جزئیات پیشنهاد ویژه مانند تخفیف، هزینه رزرو، و غیره. الزامی.
offer_restrictions	شیء (OfferRestrictions)	الزامی	توضیح می‌دهد که پیشنهاد ویژه چگونه محدود شده است، یعنی آیا اشتراک/ابزار پرداخت لازم است، آیا این پیشنهاد ویژه می‌تواند با پیشنهادهای ویژه دیگر (و چه نوعی) ترکیب شود، و غیره. الزامی است.
coupon	شیء (Coupon)		جزئیات کوپن. برای offer_category الزامی است: OFFER_CATEGORY_ADD_ON_COUPON_OFFER.
payment_instrument	شیء (PaymentInstrument)		جزئیات ابزار پرداخت. برای offer_category: OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER الزامی است.
subscription	شیء (Subscription)		جزئیات اشتراک. برای offer_category الزامی است: OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER.
terms	شیء (Terms)	الزامی	شرایط خدمات پیشنهاد ویژه. الزامی.
validity_periods	آرایه شیء (ValidityPeriod)	الزامی	دوره اعتبار پیشنهاد. توضیح می‌دهد که پیشنهاد ویژه برای چه دوره زمانی معتبر است، ازجمله زمان شروع و پایان، روزهای هفته، و غیره. الزامی.
offer_url	رشته		نشانی وب صفحه پیشنهاد ویژه فروشنده. برای offer_category: OFFER_CATEGORY_BASE_OFFER الزامی است.
tags	آرایه شمارشی (OfferTag)		برچسب‌های ویژه مرتبط با پیشنهاد. این برای شناسایی پیشنهادهای ویژه مانند «جشنواره»، «دارای بالاترین رتبه‌بندی»، «بیشترین رزروشده»، و غیره استفاده می‌شود.
brand_id	رشته		نمانام مرتبط با پیشنهاد ویژه را شناسایی می‌کند. اگر تنظیم نشده باشد، از نمانام پیش‌فرض استفاده می‌شود.
availability_level	شمارشی (AvailabilityLevel)		سطح دردسترس بودن پیشنهاد ویژه.

نام فیلد	نوع	الزام	شرح
offer_display_text	رشته	الزامی	نوشتار پیشنهادی که ارائه‌دهنده پیشنهاد می‌خواهد در صفحه نتایج جستجو به مشتریان نشان دهد. توجه داشته باشید که این ممکن است دقیقاً همان چیزی نباشد که به کاربران نشان داده می‌شود و ممکن است از فراداده‌های دیگری برای بازنویسی/بازآرایی آن استفاده کنیم. الزامی.
	oneOf (offer_specification)	الزامی	فقط یکی از فیلدها در این oneOf می‌تواند تنظیم شود.
max_discount_value	شیء (Money)		حداکثر تخفیفی که می‌توان از آن بهره‌مند شد. برای مثال، ۱۰٪ تخفیف تا سقف ۱۰۰ دلار.
min_spend_value	شیء (Money)		حداقل مقدار هزینه برای بهره‌مندی از تخفیف. برای مثال، ۱۰٪ تخفیف وقتی قیمت کل ۱۰۰ دلار یا بیشتر باشد.
booking_cost	شیء (Money)		هزینه رزرو این پیشنهاد ویژه. برای مثال، ۱۰۰ دلار تخفیف روی صورت‌حساب نهایی درصورتی‌که میز با پرداخت ۱۵ دلار رزرو شود.
booking_cost_unit	enum (FeeUnit)		واحد هزینه رزرو. برای مثال، برای هر نفر، برای هر تراکنش.
convenience_fee	شیء (Fee)
booking_cost_adjustable	بولی		آیا هزینه رزرو قابل‌تنظیم است، یعنی هزینه رزرو از صورت‌حساب نهایی کسر می‌شود. برای مثال: ۳۰٪ تخفیف برای شام با رزرو. هزینه رزرو ۱۵ دلار است و به صورت‌حساب نهایی اعمال خواهد شد. بنابراین صورت‌حساب نهایی: کل هزینه - ‎٪۳۰ - ۱۵ دلار
additional_fees	آرایه شیء (AdditionalFee)		کارمزدهای اضافی که از کاربر دریافت می‌شود. مثال‌ها: راحتی، جابه‌جایی، ارسال، بسته‌بندی، کارمزد خدمات، و غیره.
offer_discount_type	شمارشی (OfferDiscountType)		نوع تخفیف.
gift_card_info	شیء (GiftCardInfo)		جزئیات مربوط به تخفیف‌های کارت هدیه.

نام فیلد	نوع	الزام	شرح
currency_code	رشته		کد ارز سه‌حرفی تعریف‌شده در ISO 4217.
units	شماره		واحد کامل مقدار. برای مثال، اگر currencyCode برابر با "USD" باشد، ۱ واحد برابر با یک دلار امریکا است.
nanos	شماره		تعداد واحدهای نانو (۱۰^-۹) مبلغ. مقدار باید بین ۹۹۹٬۹۹۹٬۹۹۹- و ۹۹۹٬۹۹۹٬۹۹۹+ باشد و می‌تواند این دو عدد را نیز دربر بگیرد. اگر units مثبت باشد، nanos باید مثبت یا صفر باشد. اگر units صفر باشد، nanos می‌تواند مثبت، صفر، یا منفی باشد. اگر units منفی است، nanos باید منفی یا صفر باشد. برای مثال، ‎-۱٫۷۵ دلار به‌صورت units=-۱ و nanos=-۷۵۰٬۰۰۰٬۰۰۰ نشان داده می‌شود.

نام فیلد	نوع	الزام	شرح
unit	enum (FeeUnit)
type	شمارشی (FeeType)
	oneOf (cost)		فقط یکی از فیلدها در این oneOf می‌تواند تنظیم شود.

نام فیلد	نوع	الزام	شرح
min_amount	شیء (Money)
max_amount	شیء (Money)

نام فیلد	نوع	الزام	شرح
name	رشته	الزامی	نام کارمزد اضافی. مثال‌ها: هزینه تسهیلات، هزینه تحویل و غیره. الزامی است.
fee	شیء (Fee)

نام فیلد	نوع	الزام	شرح
	oneOf (denomination_type)		فقط یکی از فیلدها در این oneOf می‌تواند تنظیم شود.

نام فیلد	نوع	الزام	شرح
amounts	آرایه شیء (Money)		فهرستی از همه مبالغ مجزای دردسترس (مثلاً [۱۰۰، ۵۰۰، ۱۰۰۰]).

نام فیلد	نوع	الزام	شرح
combinable_with_other_offers	بولی		آیا این پیشنهاد ویژه را می‌توان با پیشنهادهای ویژه دیگر ترکیب کرد. وقتی درست باشد، شرکا می‌توانند مشخص کنند این پیشنهاد با چه پیشنهادهایی می‌تواند ترکیب شود. اگر هر دو combinable_offer_categories و combinable_offer_ids تنظیم شده باشند، هر پیشنهادی که با یکی از شرایط بالا مطابقت داشته باشد قابل‌ترکیب خواهد بود.
combinable_offer_categories	آرایه شمارشی (OfferCategory)		فهرست انواع پیشنهادهای ویژه‌ای که این پیشنهاد ویژه می‌تواند با آن‌ها ترکیب شود. برای مثال، این پیشنهاد ممکن است با «کوپن‌های» دیگر قابل‌ترکیب باشد. اگر combinable_with_other_offers درست باشد و این فیلد تنظیم نشده باشد، همه انواع قابل ترکیب خواهند بود.
combinable_offer_ids	آرایه رشته		فهرست offer_ids که این پیشنهاد ویژه می‌تواند با آن‌ها ترکیب شود. برخی‌از پیشنهادهای ویژه ممکن است فقط با offer_idهای خاص دیگر ترکیب شوند (می‌توانند پیشنهادهای ویژه اصلی درنظر گرفته شوند). اگر combinable_with_other_offers درست باشد و این فیلد تنظیم نشده باشد، همه شناسه‌های پیشنهاد ویژه قابل‌ترکیب خواهند بود.
inclusions	آرایه شیء (OfferCondition)		فهرست شرایطی که باید رعایت شود تا پیشنهاد معتبر باشد (برای نمونه، نوشیدنی‌های غیرالکلی، غذا).
exclusions	آرایه شیء (OfferCondition)		فهرست شرایطی که پیشنهاد ویژه را نامعتبر می‌کند (مثلاً بوفه، پیشنهادهای ترکیبی، و کوکتل).
min_guest	شماره		حداقل تعداد افراد لازم برای بهره‌مندی از پیشنهاد ویژه. توجه: این فیلد فقط برای رزروهای غذاخوری کاربرد دارد و نباید برای عمودی‌های دیگر استفاده شود.
food_offer_restrictions	شیء (FoodOfferRestrictions)		محدودیت‌های خاص برای پیشنهادهای غذایی.
max_redemption_count	شماره		محدودیت‌های خاص مربوط به تعداد دفعاتی که می‌توان از این پیشنهاد ویژه استفاده کرد. مقدار ۰ مشخص می‌کند که هیچ محدودیتی وجود ندارد. برای مثال، مقدار ۳ یعنی کاربر می‌تواند ۳ بار از این پیشنهاد ویژه استفاده کند.
max_total_discount_value	شیء (Money)		حداکثر تخفیفی که می‌توانید در چندین تراکنش این پیشنهاد ویژه دریافت کنید.
special_conditions	آرایه رشته		شرایط ویژه این پیشنهاد که باید به کاربر نشان داده شود. مثال‌ها: «فقط برای پرداخت در [منطقه] معتبر است»، «پرداخت‌های آنلاین را شامل نمی‌شود»، «از «گشت‌برگ هدیه» می‌توان درطول «حراج» استفاده کرد.»

نام فیلد	نوع	الزام	شرح
description	رشته

نام فیلد	نوع	الزام	شرح
meal_types	آرایه شمارشی (MealType)		انواع وعده‌های غذایی که پیشنهاد ویژه می‌تواند برای آن‌ها اعمال شود، مثل ناهار یا شام. اگر تنظیم نشده باشد، پیشنهاد ویژه می‌تواند برای همه انواع وعده‌های غذایی اعمال شود.
restricted_to_certain_courses	بولی		آیا پیشنهاد فقط برای دوره‌های خاصی قابل اعمال است.

نام فیلد	نوع	الزام	شرح
text	رشته		نوشتار کوپنی که ارائه‌دهنده پیشنهاد ویژه می‌خواهد به کاربران نمایش دهد.
code	رشته	الزامی	برای پس‌خرید کردن پیشنهاد ویژه، کد تخفیف لازم است. الزامی.

نام فیلد	نوع	الزام	شرح
items	آرایه شیء (PaymentInstrumentItem)	الزامی	فهرست ابزارهای پرداخت که می‌توان از آن‌ها برای استفاده از پیشنهاد ویژه استفاده کرد. الزامی.
provider_name	رشته		نام ارائه‌دهنده ابزار پرداخت. می‌تواند شریک بانکی، نام بانک، و غیره باشد. برای مثال: American Express،‏ HDFC،‏ ICICI.

نام فیلد	نوع	الزام	شرح
type	شمارشی (PaymentInstrumentType)	الزامی	نوع ابزار پرداخت. الزامی.
name	رشته	الزامی	نام مورد ابزار پرداخت، مثل نام کارت اعتباری. برای مثال: HDFC Infinia،‏ American Express Platinum. الزامی.

نام فیلد	نوع	الزام	شرح
name	رشته	الزامی	نام اشتراک. الزامی.
subscription_auto_added	بولی		اینکه آیا وقتی کاربر از این پیشنهاد ویژه استفاده می‌کند، اشتراک به‌طور خودکار اضافه می‌شود یا نه
cost	شیء (Money)	الزامی	هزینه اشتراک. الزامی.
subscription_duration	شیء (Duration)	الزامی	مدت زمانی که اشتراک با subscription_cost معتبر است. الزامی.
terms_and_conditions_url	رشته		نشانی وب شرایط خدمات شریک مربوط به این اشتراک.

نام فیلد	نوع	الزام	شرح
seconds	شماره		ثانیه‌های علامت‌دار بازه زمانی. باید از ‎-۳۱۵٬۵۷۶٬۰۰۰٬۰۰۰ تا ‎+۳۱۵٬۵۷۶٬۰۰۰٬۰۰۰ فراگیر باشد. توجه: این حدود از این فرمول محاسبه شده است: ۶۰ ثانیه/دقیقه * ۶۰ دقیقه/ساعت * ۲۴ ساعت/روز * ۳۶۵٫۲۵ روز/سال * ۱۰۰۰۰ سال
nanos	شماره		کسرهای علامت‌دار ثانیه در وضوح نانوثانیه از بازه زمانی. مدت‌های کمتر از یک ثانیه با فیلد 0 seconds و فیلد مثبت یا منفی nanos نشان داده می‌شوند. برای مدت‌های یک ثانیه یا بیشتر، مقدار غیرصفر برای فیلد nanos باید هم‌علامت با فیلد seconds باشد. باید از ۹۹۹٬۹۹۹٬۹۹۹- تا ۹۹۹٬۹۹۹٬۹۹۹+ فراگیر باشد.

نام فیلد	نوع	الزام	شرح
url	رشته		نشانی وب شرایط خدمات شریک.
restricted_to_certain_users	بولی		آیا پیشنهاد ویژه به کاربران خاصی محدود شده است یا نه.
terms_and_conditions	رشته		نوشتار اصلی «شرایط خدمات» ارائه‌شده توسط شریک.
additional_terms_and_conditions	آرایه رشته		شرایط خدمات علاوه‌بر شرایط خدمات اصلی شریک.

نام فیلد	نوع	الزام	شرح
valid_period	شیء (ValidityRange)		مُهر زمان شروع و پایان که پیشنهاد ویژه برای آن معتبر است. این زمان‌ها باید نشان‌دهنده روزهای متمایز باشند، یعنی زمان شروع باید ۰۰:۰۰ (ابتدای روز) و زمان پایان باید ۰۰:۰۰ (انحصاری) در روزی باشد که دوره اعتبار به‌پایان می‌رسد.
time_of_day	آرایه شیء (TimeOfDayWindow)		بازه زمانی معتبر را در روزی مشخص و اینکه کدام روزها برای پیشنهاد ویژه دردسترس است مشخص می‌کند. برای بازه‌های زمانی که از نیمه‌شب عبور می‌کنند (برای نمونه، ۱۰ شب تا ۲ بامداد)، از پنجره‌های جداگانه برای هر روز استفاده کنید: یکی که در ساعت ۱۱:۵۹:۵۹ شب تمام می‌شود و دیگری که در ساعت ۱۲:۰۰ بامداد روز بعد شروع می‌شود. برای مثال: دوشنبه: ۱۰ صبح تا ۵ عصر سه‌شنبه: ۱۰ صبح تا ۲ بعدازظهر سه‌شنبه: ۵ عصر تا ۷ شب چهارشنبه، پنج‌شنبه، جمعه، شنبه، یکشنبه: ۳ بعدازظهر تا ۷ شب اگر هیچ‌کدام تنظیم نشده باشد، یعنی پیشنهاد ویژه در تمام زمان‌های valid_period دردسترس است.
time_exceptions	آرایه شیء (ValidTimeException)		استثناهای valid_period و valid_time_of_week بالا را مشخص می‌کند
date_exceptions	آرایه شیء (Date)		استثناهایی را در روزهای valid_period و time_of_day مشخص می‌کند
validity_scope	شمارشی (ValidityScope)		محدوده دوره اعتبار را مشخص می‌کند.
validity_duration_in_days	شماره		مدت (به روز) اعتبار گشت‌برگ/کوپن پس‌از خرید.

نام فیلد	نوع	الزام	شرح
valid_from_time	شیء (Timestamp)	الزامی	زمان شروع محدوده (فراگیر). الزامی.
valid_through_time	شیء (Timestamp)		زمان پایان محدوده (انحصاری). اگر تنظیم نشده باشد، به این معنی است که این دوره هرگز پایان نمی‌یابد. اختیاری.

نام فیلد	نوع	الزام	شرح
seconds	شماره		نشان‌دهنده ثانیه‌های زمان «ساعت هماهنگ جهانی» از تاریخ یونیکس 1970-01-01T00:00:00Z است. باید بین ‎-۶۲۱۳۵۵۹۶۸۰۰ و ۲۵۳۴۰۲۳۰۰۷۹۹ (شامل این دو عدد) باشد (که معادل 0001-01-01T00:00:00Z تا 9999-12-31T23:59:59Z است).
nanos	شماره		کسرهای غیرمنفی ثانیه با وضوح نانوثانیه. این فیلد بخش نانوثانیه مدت است، نه جایگزینی برای ثانیه. مقادیر ثانیه منفی با کسرهای اعشاری باید همچنان مقادیر نانوثانیه غیرمنفی داشته باشند که در زمان به جلو شمارش می‌کنند. باید بین ۰ تا ۹۹۹٬۹۹۹٬۹۹۹ فراگیر باشد.

نام فیلد	نوع	الزام	شرح
time_windows	شیء (TimeOfDayRange)	الزامی	بازه زمانی‌ای که سفارش می‌تواند ثبت/انجام شود. الزامی.
day_of_week	آرایه شمارشی (DayOfWeek)		فهرست روزهای هفته که پنجره‌ها اعمال می‌شوند. اگر هیچ‌کدام تنظیم نشده باشد، یعنی برای همه روزهای هفته اعمال می‌شود. اختیاری.
day_of_month	آرایه شیء (DayOfMonthRange)		روزهایی از ماه که پنجره‌ها اعمال می‌شوند. اگر هیچ‌کدام تنظیم نشده باشد، یعنی برای همه روزهای ماه اعمال می‌شود. اختیاری.

نام فیلد	نوع	الزام	شرح
open_time	شیء (TimeOfDay)		«زمان» نشان‌دهنده زمان شروع روز محدوده (فراگیر). اگر تنظیم نشده باشد، به‌معنای 00:00:00 است. اختیاری.
close_time	شیء (TimeOfDay)		زمان نشان‌دهنده زمان پایان روز محدوده (انحصاری). اگر تنظیم نشده باشد، به‌معنای ۲۳:۵۹:۵۹ است. اختیاری.

نام فیلد	نوع	الزام	شرح
hours	شماره		ساعت‌های روز در قالب ۲۴ ساعته. باید بزرگ‌تر یا مساوی ۰ باشد و معمولاً باید کوچک‌تر یا مساوی ۲۳ باشد. ممکن است API انتخاب کند که مقدار «24:00:00» را برای سناریوهایی مثل زمان بسته شدن کسب‌وکار مجاز کند.
minutes	شماره		دقیقه‌های یک ساعت. باید بزرگ‌تر یا مساوی با ۰ و کوچک‌تر یا مساوی با ۵۹ باشد.
seconds	شماره		ثانیه‌های یک دقیقه. باید بزرگ‌تر یا مساوی ۰ و معمولاً باید کوچک‌تر یا مساوی ۵۹ باشد. اگر یک API ثانیه‌های کبیسه را مجاز کند، ممکن است مقدار ۶۰ را مجاز کند.
nanos	شماره		کسری از ثانیه، برحسب نانوثانیه. باید بزرگ‌تر یا مساوی با ۰ و کوچک‌تر یا مساوی با ۹۹۹٬۹۹۹٬۹۹۹ باشد.

نام فیلد	نوع	الزام	شرح
valid_from_day	شماره	الزامی	روز آغازین محدوده (فراگیر). الزامی.
valid_through_day	شماره		روز پایان محدوده (شامل). اگر تنظیم نشده باشد، یعنی این محدوده نشان‌دهنده یک روز است (valid_from_day). اختیاری.

نام فیلد	نوع	الزام	شرح
exceptional_period	شیء (ValidityRange)		مُهر زمان شروع و پایان که پیشنهاد ویژه برای آن معتبر نیست. این زمان‌ها باید نشان‌دهنده روزهای متمایز باشند، یعنی زمان شروع باید ۰۰:۰۰ (آغاز روز) و زمان پایان باید ۰۰:۰۰ (بدون احتساب) در روزی باشد که دوره استثنا پایان می‌یابد.

نام فیلد	نوع	الزام	شرح
year	شماره		سال تاریخ. باید از ۱ تا ۹۹۹۹ باشد، یا ۰ برای مشخص کردن تاریخ بدون سال.
month	شماره		ماهی از سال. باید از ۱ تا ۱۲ باشد، یا ۰ برای مشخص کردن سال بدون ماه و روز.
day	شماره		روز ماه. باید از ۱ تا ۳۱ و برای سال و ماه معتبر باشد، یا ۰ برای مشخص کردن سال به‌تنهایی یا سال و ماه در جایی که روز مهم نیست.

نام	شرح
OFFER_SOURCE_UNSPECIFIED
OFFER_SOURCE_AGGREGATOR

نام	شرح
ACTION_TYPE_UNSPECIFIED
ACTION_TYPE_FOOD_DELIVERY	این پیشنهاد ویژه برای خدمات ارسال غذا اعمال می‌شود.
ACTION_TYPE_FOOD_TAKEOUT	این پیشنهاد ویژه برای سفارش‌های غذای بیرون‌بر یا تحویل در فروشگاه اعمال می‌شود.
ACTION_TYPE_DINING	این پیشنهاد ویژه برای غذا خوردن در محل رستوران است.
ACTION_TYPE_APPOINTMENT	این پیشنهاد ویژه برای خدمات رزرو قرار قابل‌اعمال است.
ACTION_TYPE_SHOPPING_IN_STORE	این پیشنهاد ویژه برای خریدهای آفلاین و درون‌فروشگاهی قابل‌اعمال است.

نام	شرح
OFFER_MODE_OTHER	استفاده برای روش‌های انجام سفارش که تحت پوشش سایر حالت‌های خاص نیستند.
OFFER_MODE_WALK_IN	این پیشنهاد ویژه برای بازدیدهای حضوری بدون رزرو قبلی دردسترس است.
OFFER_MODE_FREE_RESERVATION	این پیشنهاد زمانی اعمال می‌شود که کاربر رزروی انجام دهد که نیازی به پیش‌پرداخت نداشته باشد.
OFFER_MODE_PAID_RESERVATION	این پیشنهاد ویژه زمانی اعمال می‌شود که کاربر رزروی انجام دهد که نیاز به پرداخت پیش‌پرداخت داشته باشد.
OFFER_MODE_ONLINE_ORDER	این پیشنهاد ویژه برای سفارش‌هایی که ازطریق وب‌سایت یا پلاتفرم دیجیتال ثبت شده‌اند معتبر است.
OFFER_MODE_GIFT_CARD_PURCHASE	نشان می‌دهد خرید کارت هدیه اولین مرحله لازم برای دریافت معامله است.

نام	شرح
OFFER_CATEGORY_UNSPECIFIED	مقدار شمارشی «نامشخص» یا پیش‌فرض نباید در فیدها استفاده شود.
OFFER_CATEGORY_BASE_OFFER
OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER
OFFER_CATEGORY_ADD_ON_COUPON_OFFER
OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER
OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER

نام	شرح
FEE_UNIT_UNSPECIFIED	مقدار UNSPECIFIED یا مقدار پیش‌فرض enum نباید در فیدها استفاده شود.
FEE_UNIT_PER_GUEST
FEE_UNIT_PER_TRANSACTION

نام	شرح
FEE_TYPE_UNSPECIFIED	مقدار شمارشی «نامشخص» یا پیش‌فرض نباید در فیدها استفاده شود.
FEE_TYPE_FIXED
FEE_TYPE_VARIABLE

نام	شرح
OFFER_DISCOUNT_TYPE_UNSPECIFIED
OFFER_DISCOUNT_TYPE_INSTANT_DISCOUNT
OFFER_DISCOUNT_TYPE_CASHBACK
OFFER_DISCOUNT_TYPE_REWARD_POINT

نام	شرح
MEAL_TYPE_UNSPECIFIED	مقدار شمارشی UNSPECIFIED یا پیش‌فرض نباید در فیدها استفاده شود.
MEAL_TYPE_BREAKFAST
MEAL_TYPE_LUNCH
MEAL_TYPE_DINNER

نام	شرح
PAYMENT_INSTRUMENT_TYPE_UNSPECIFIED	مقدار شمارشی UNSPECIFIED یا پیش‌فرض نباید در فیدها استفاده شود.
PAYMENT_INSTRUMENT_CREDIT_CARD
PAYMENT_INSTRUMENT_DEBIT_CARD
PAYMENT_INSTRUMENT_BANK_ACCOUNT
PAYMENT_INSTRUMENT_UPI
PAYMENT_INSTRUMENT_ONLINE_WALLET
PAYMENT_INSTRUMENT_NETBANKING

نام	شرح
DAY_OF_WEEK_UNSPECIFIED	روز هفته مشخص نشده است.
MONDAY	ﺪﻮﺷﻨﺑﮫ
TUESDAY	سه‌شنبه
WEDNESDAY	چهارشنبه
THURSDAY	پنج‌شنبه
FRIDAY	جمعه
SATURDAY	شنبه
SUNDAY	یک‌شنبه

نام	شرح
VALIDITY_SCOPE_UNSPECIFIED
VALIDITY_SCOPE_CLAIM
VALIDITY_SCOPE_REDEEM

نام	شرح
OFFER_TAG_UNSPECIFIED	مقدار شمارشی «نامشخص» یا پیش‌فرض نباید در فیدها استفاده شود.
OFFER_TAG_NEW_YEAR_SPECIAL
OFFER_TAG_VALENTINES_SPECIAL

نام	شرح
AVAILABILITY_LEVEL_UNSPECIFIED
AVAILABILITY_LEVEL_LOW	نشان می‌دهد که پیشنهاد ویژه درحال اتمام است. به کاربران توصیه می‌شود آن را قبل‌از اتمام موجودی پس‌خرید کنند. ممکن است بعداً «متوسط» و «بالا» را اضافه کنیم.

نام فیلد	نوع	الزام	شرح
discount_percent	شماره	با discount_value،‏ other_offer_detail_text متقابلاً انحصاری است	درصدی از صورت‌حساب که تخفیف داده می‌شود. [0, 100] برای پیشنهادهای ویژه «یکی بخر، یکی رایگان بگیر» یا ۵۰٪ تخفیف که برای کل وعده غذایی اعمال می‌شود (مثلاً بوفه «یکی بخر، یکی رایگان بگیر»، «یکی بخر، یکی رایگان بگیر» برای کل صورت‌حساب، «یکی بخر، یکی رایگان بگیر» برای منوِ ثابت)، این مقدار می‌تواند روی ۵۰ تنظیم شود.
discount_value	شیء (Money)	با discount_percent،‏ other_offer_detail_text ناسازگار است	مقدار ثابت تخفیف.
other_offer_detail_text	رشته	با discount_percent،‏ discount_value ناسازگار است	نوشتار آزاد برای شرح تخفیف. برای پیشنهادهای ویژه ۱+۱ (مثلاً ۱+۱ نوشیدنی، +۱ غذای اصلی، ۱+۱ از موارد منو انتخابی)، این جزئیات باید در اینجا شرح داده شود.

نام فیلد	نوع	الزام	شرح
amount	شیء (Money)	با amount_range ناسازگار است
amount_range	شیء (MoneyRange)	با amount متقابلاً انحصاری است

نام فیلد	نوع	الزام	شرح
fixed_denominations	شیء (FixedDenominations)	ناسازگار با custom_range	وقتی کارت هدیه در مقادیر ثابت و مشخص دردسترس باشد استفاده می‌شود.
custom_range	شیء (MoneyRange)	با fixed_denominations متقابلاً انحصاری است	وقتی نمانام به کاربران اجازه می‌دهد مقدار اسمی سفارشی (انعطاف‌پذیر) را در محدوده تعریف‌شده‌ای انتخاب کنند استفاده می‌شود.

بارگذاری فید

فید پیشنهادها باید در سرور SFTP فید Generic بارگذاری شود. برای دریافت دستورالعمل‌ها، آموزش نحوه استفاده از سرور SFTP فید عمومی را دنبال کنید و از مجموعه name روی google.offer در فایل توصیفگر استفاده کنید.

بسامد بارگذاری

به‌طور کلی، Google انتظار دارد ۱ بارگذاری فید در روز انجام شود. بسته به دفعات به‌روزرسانی پیشنهاد ویژه ازطرف شما، ممکن است دفعات بارگذاری افزایش یا کاهش یابد تا دقت بالا به‌طور مداوم تضمین شود. با «مسئول تماس Google» خود مشورت کنید.

چند ساعت طول می‌کشد تا داده‌ها در Google نشان داده شود.

دسته‌بندی پیشنهادها

• OFFER_CATEGORY_BASE_OFFER: پیشنهادهای ویژه‌ای که می‌توان به‌طور مستقل بدون ترکیب با پیشنهاد ویژه دیگر مطالبه کرد. این شامل موارد زیر می‌شود:
  • تخفیف ثابت روی کل صورت‌حساب (مثلاً، ۲۰٪ تخفیف)
  • پیشنهادهای اشتراک (مثلاً، دسر رایگان با عضویت)
  • پیشنهادهای پرداخت در مواردی که هیچ پیشنهاد پایه دیگری برای رستوران وجود ندارد
  • توجه: پیشنهادهای ویژه کاهش کارمزد یا چشم‌پوشی از کارمزد در سراسر پلاتفرم نباید به‌عنوان پیشنهاد ویژه پایه تنظیم شوند.
• پیشنهادهای ویژه برافزا: پیشنهادهای ویژه‌ای که برای مطالبه شدن به پیشنهاد ویژه پایه نیاز دارند. این موارد عبارت‌اند از:
  • OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER (مثلاً، ۱۰٪ تخفیف بیشتر با کارت اعتباری خاص)
  • ‫OFFER_CATEGORY_ADD_ON_COUPON_OFFER (برای نمونه، نوشیدنی رایگان با کد تخفیف ویژه)
  • ‫OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER (برای نمونه، ۱۰٪ تخفیف بیشتر برای مشترکین)
  • OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER (مثلاً ارسال رایگان یا کارمزد کاهش‌یافته)

ملاحظات دیگر:

• پیشنهادهای کاهش یا چشم‌پوشی از کارمزد در سراسر پلاتفرم نباید به‌عنوان پیشنهادهای پایه (OFFER_CATEGORY_BASE_OFFER) تنظیم شوند. این پیشنهادها باید فقط به‌عنوان OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER تنظیم شوند تا مکمل پیشنهاد پایه فعال دیگری باشند.
• وقتی رستورانی «پیشنهاد پایه» تنظیم نکرده باشد، «پیشنهادهای مکمل» نمایش داده نخواهد شد. اگر «پیشنهاد پایه» وجود نداشته باشد، هر «پیشنهاد پرداخت»، «اشتراک»، یا «کوپن» که بتواند بدون نیاز به اضافه شدن به پیشنهاد دیگری مطالبه شود باید به‌عنوان OFFER_CATEGORY_BASE_OFFER برچسب‌گذاری شود.
  • بسته به نوع، داده‌های مربوط به PaymentInstrument، Subscription، یا Coupon باید تنظیم شود.
  • شرکا باید ۲ نسخه از هریک از این پیشنهادهای ویژه را ارائه دهند تا سناریوهایی را که در آن‌ها هم به‌عنوان «پیشنهادهای ویژه پایه» و هم به‌عنوان «پیشنهادهای ویژه برافزایی» عمل می‌کنند پوشش دهند. سپس می‌توان نسخه «پیشنهاد مکمل» را بااستفاده از entity_ids یا add_on_offer_applicable_to_all_entities برای چندین رستوران تنظیم کرد.
• وقتی رستورانی چند «پیشنهاد پایه» دارد که می‌توانند روی‌هم قرار بگیرند، همه «پیشنهادهای پایه» باید به‌عنوان OFFER_CATEGORY_BASE_OFFER برچسب‌گذاری شوند، و «پیشنهادهای پایه» که پیشنهادهای «پرداخت»، «اشتراک»، یا «کوپن» هستند باید علاوه‌براین به‌عنوان نوع «پیشنهاد مکمل» مربوطه ارسال شوند.
• ValidityPeriod باید برای فعال کردن پیشنهادهای ویژه «برافزایی» به‌عنوان «پیشنهادهای ویژه پایه» فقط زمانی استفاده شود که «پیشنهاد ویژه پایه» فعال وجود نداشته باشد.
• ادغام پیشنهادهای یکسان براساس ابزار پرداخت: اگر چند ابزار پرداخت مقدار تخفیف دقیقاً یکسانی را ارائه می‌دهند (برای مثال، کارت اعتباری، کارت نقدی، و بانکداری اینترنتی همگی ۵٪ تخفیف ارائه می‌دهند)، آن‌ها را تحت یک شیء Offer ادغام‌شده گروه‌بندی کنید، به‌جای اینکه پیشنهادهای تکراری جداگانه ارسال کنید. برای انجام این کار، فهرست payment_instrument.items را با همه ابزارهای پرداخت ذی‌ربط تکمیل کنید. این کار باعث کاهش به‌هم‌ریختگی چیدمان در واسط Google می‌شود و از افت احتمالی رتبه‌بندی به‌دلیل محدودیت‌های تکراری بیش‌ازحد جلوگیری می‌کند.

سناریوهای نمونه:

• رستورانی ۵٪ تخفیف برای پرداخت با کارت اعتباری خاصی و نوشیدنی رایگان با کد کوپن خاصی ارائه می‌دهد

  • پیشنهاد ۵٪ تخفیف کارت اعتباری باید به‌صورت ۲ نسخه ارسال شود، یکی با برچسب OFFER_CATEGORY_BASE_OFFER و دیگری با برچسب OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER با جزئیات PaymentInstrument گنجانده‌شده.
  • نوشیدنی رایگان با پیشنهاد کد تخفیف باید به‌صورت OFFER_CATEGORY_ADD_ON_COUPON_OFFER با جزئیات Coupon ارسال شود.

• رستورانی برای مشتریان حضوری ۱۰٪ تخفیف و برای پرداخت با کارت اعتباری خاص ۵٪ تخفیف ارائه می‌دهد که هر دو تخفیف را می‌توان با هم ترکیب کرد.

  • پیشنهاد ویژه ۱۰٪ تخفیف مشتریان حضوری باید با OFFER_CATEGORY_BASE_OFFER برچسب‌گذاری شود.
  • پیشنهاد ویژه کارت اعتباری با ۵٪ تخفیف باید ۲ نسخه داشته باشد، یکی با برچسب OFFER_CATEGORY_BASE_OFFER و دیگری با برچسب OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.

• رستورانی ۱۰٪ تخفیف فقط برای ناهار در روزهای کاری هفته و ۵٪ تخفیف برای هر زمان دیگری درصورت پرداخت با کارت اعتباری خاصی ارائه می‌دهد.

  • پیشنهاد ۱۰٪ تخفیف باید ValidityPeriod تنظیم شود تا نشان دهد فقط در ساعات ناهار رستوران در روزهای هفته است.
  • پیشنهاد ویژه ۵٪ تخفیف کارت اعتباری باید به‌صورت ۲ نسخه ارسال شود.
    • یک نسخه باید با برچسب OFFER_CATEGORY_BASE_OFFER و با جزئیات PaymentInstrument علامت‌گذاری شود. ValidityPeriod باید تنظیم شود تا ساعات ناهار در روزهای هفته که پیشنهاد ویژه ۱۰٪ تخفیف برای ناهار فعال است مستثنا شود
    • یک نسخه باید با برچسب OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER و با جزئیات PaymentInstrument ارائه شود.
  • همه «پیشنهادهای پرداخت» دیگر برای این رستوران باید با برچسب OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER علامت‌گذاری شوند.

فرایند توسعه و راه‌اندازی

درطول یکپارچه‌سازی، درگاه شریک می‌تواند براساس توسعه شما، با ارائه اطلاعات و بازخورد به شما کمک کند. فرایند توسعه از این جریان پیروی می‌کند:

• ادغام ابتدا در محیط Sandbox توسعه داده خواهد شد. باید از برون‌برد تولید (یا حتی مستقیماً از داده‌های تولید) در محیط Google Sandbox استفاده کنید. این کار کمک می‌کند مطمئن شوید که توسعه شما همه موارد حاشیه‌ای را پوشش می‌دهد و به Google امکان می‌دهد کیفیت داده‌ها را ارزیابی کند و براساس مدل داده‌هایتان بهتر به شما کمک کند.
• وقتی بارگذاری فیدهای کامل و روزانه «فروشنده»، «خدمات»، و «معاملات» را به‌طور مداوم در محیط «جعبه امن Google» انجام دادید، تیم Google فیدهایتان را ارزیابی خواهد کرد. پس‌از اینکه تیم Google تأیید کرد، می‌توانید کدتان را به محیط تولید ارسال کنید و ارسال داده‌های تولید به محیط تولید Google را آغاز کنید.
• پس‌از اینکه ادغام «تولید» را به‌طور کامل آزمایش کردید، تیم Google نیز آن را آزمایش خواهد کرد. وقتی همه آزمایش‌ها تکمیل شد، یکپارچه‌سازی شما راه‌اندازی خواهد شد.

پایش کردن

برای اطمینان از تجربه کاربری خوب، Google قبل و بعداز راه‌اندازی بررسی می‌کند که پیشنهادهای ویژه ارائه‌شده معتبر و صحیح باشند و معیارهای خط‌مشی ما را برآورده کنند. برای انجام این کار، ‫Google از ترکیبی از بازبینی انسانی و خودکارشده استفاده خواهد کرد. نتیجه این بررسی‌ها در داشبورد پیشنهاد «مرکز اقدامات» (فقط تولید) دردسترس خواهد بود. از نتیجه این پایش ممکن است برای تأثیرگذاری بر رتبه‌بندی پیشنهادهای ویژه استفاده شود.

مطمئن شوید که بار شدن کامل صفحه با پیشنهادها کمتر از ۵ ثانیه طول می‌کشد، درغیراین‌صورت این مورد به‌عنوان خطا درنظر گرفته می‌شود و با پرچم Bad link علامت‌گذاری می‌شود.

بررسی‌های خودکار (خزنده‌ها)

تیم کیفیت Google خزنده‌ها را پیاده‌سازی می‌کند. خزنده‌ها برنامه‌هایی هستند که مرورگر وب را برای انجام برخی کلیک‌ها و استخراج اطلاعات پیشنهاد ویژه به‌طور خودکار درمی‌آورند، فقط برای اهداف آزمایش کیفیت.

تعداد پُرسمان‌ها

برای مثال، اگر تصمیم بگیریم ۵۰۰۰ بررسی در روز ارسال کنیم، به این معنی است که ۵۰۰۰ بار در روز (به‌طور مساوی درطول روز توزیع می‌شود، یعنی تقریباً هر ۱۷ ثانیه یک‌بار)، خزنده ما همه اقدامات زیر را که یک کاربر معمولی انجام می‌دهد انجام می‌دهد:

• از «جستجوی Google» شروع کنید و روی پیوند شریک کلیک کنید.
• اطلاعات پیشنهاد ویژه را پیدا کنید.
• اگر پیشنهاد ویژه نیاز به رزرو داشته باشد، به جریان رزرو هدایت می‌شوید تا تأیید کنید پیشنهاد ویژه در زمان مشخص‌شده دردسترس است (رزرو انجام نخواهد شد).

تشخیص وب‌کاوشگر

برای اطمینان از اینکه وب‌خراش مسدود نمی‌شود (که ممکن است باعث شود به این نتیجه برسد که پیشنهادها دردسترس نیستند)، مطمئن شوید که سیستم شما به وب‌خراش ما اجازه می‌دهد در هر زمانی صفحه شما را جست‌وجو کند. برای شناسایی وب‌کاوشگر ما:

• «عامل کاربر» وب‌تراش شامل رشته «Google-Offers» خواهد بود:
  • مثال: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko; Google-Offers) Chrome/104.0.5112.101 Safari/537.36
• همچنین می‌توانید بااستفاده از ساناد معکوس، همان‌طور که در «درستی‌سنجی Googlebot و دیگر خزنده‌های Google» توصیه شده است، بررسی کنید که آیا تماس‌ها از Google می‌آیند یا نه. در مورد خاص ما، حل‌وفصل ساناد معکوس از این الگو پیروی می‌کند: google-proxy-***-***-***-***.google.com.

رفتار فنی

در حال ذخیره در حافظه نهان

به‌منظور کاهش بار روی وب‌سایت شریک، خزنده‌های ما معمولاً پیکربندی می‌شوند تا همه سرایندهای استاندارد حافظه نهان HTTP موجود در پاسخ را رعایت کنند. این یعنی برای وب‌سایت‌هایی که به‌درستی پیکربندی شده‌اند، از واکشی مکرر محتوایی که به‌ندرت تغییر می‌کند (مثلاً کتابخانه‌های جاوا اسکریپت) اجتناب می‌کنیم. برای جزئیات بیشتر درباره نحوه پیاده‌سازی ذخیره کردن در حافظه نهان، این سند ذخیره کردن در حافظه نهان HTTP را بخوانید.