پاسخ را بسازید
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
پس از اینکه برنامه شما درخواست پیشنهاد از گوگل را پردازش کرد، باید پاسخی ایجاد و ارسال کند. این راهنما نحوه کدنویسی برنامه شما برای ایجاد پاسخ را توضیح میدهد.
ایجاد پیام BidResponse
برای ارسال پیشنهاد، برنامه پیشنهاد شما باید به درخواست پیشنهاد با یک BidResponse حاوی یک Bid در قالب پیکربندی شده شما پاسخ دهد. اگر از قالب JSON استفاده میکنید، پاسخ شما باید هدر Content-Type را روی application/json; charset=utf-8 تنظیم کند و JSON BidResponse در بدنه قرار دهد. اگر از قالب Protobuf استفاده میکنید، برنامه شما باید هدر Content-Type را روی application/octet-stream تنظیم کند و BidResponse سریالی شده را در بدنه قرار دهد.
برای ساخت و سریالایز کردن یک BidResponse برای فرمت Protobuf، باید کتابخانههای Protobuf را بر اساس openrtb.proto و openrtb-adx.proto تولید و استفاده کنید، که به ترتیب فیلدهای استاندارد OpenRTB BidResponse و افزونههای گوگل را در Protobuf پیادهسازی میکنند. این موارد را میتوانید در Protos & Reference Data پیدا کنید.
اگر نمیخواهید برای یک نمایش پیشنهاد قیمت بدهید، باید یک پاسخ HTTP 204 خالی برگردانید. برنامه شما باید به هر BidRequest پاسخی برگرداند. وقفهها و پاسخهایی که قابل تجزیه نیستند، خطا محسوب میشوند و گوگل پیشنهاددهندگانی را که نرخ خطای بالایی دارند، مسدود میکند.
شناسه خلاق
BidResponse شما یک آگهی تبلیغاتی را از طریق فیلد BidResponse.seatbid.bid.crid (محدودیت ۱۲۸ بایت) مشخص میکند. حتی آگهیهای تبلیغاتی مشابه نیز در صورت تفاوت در هر ویژگی قابل توجه، از جمله اما نه محدود به موارد زیر، باید مقادیر منحصر به فردی برای این فیلد داشته باشند: اندازه، URL اعلام شده، ویژگیهای آگهی تبلیغاتی و انواع فروشنده. به عبارت دیگر، شما باید به هر دو آگهی که:
متفاوت به نظر برسید یا رفتار کنید.
رندر کردن روی تصاویر مختلف
به روشهای مختلف رندر کنید (برای مثال، یک تبلیغ شامل یک تصویر است، در حالی که دیگری یک ویدیو است).
همانطور که درخواست خود را طراحی میکنید، باید در مورد یک روش سیستماتیک برای تولید شناسهها تصمیم بگیرید که برای انواع آثار خلاقانهای که قصد ارسال آنها را دارید، منطقی باشد.
ویژگیهای تبلیغ
گوگل توصیه میکند برای توصیف ویژگیهای تبلیغ و هدفگیری آن، ویژگیهای خلاقانه را با استفاده از ترکیبی از BidResponse.seatbid.bid.apis و BidResponse.seatbid.bid.attr یا افزونهی BidResponse.seatbid.bid.ext.attribute اعلام کنید. در ادامه نحوهی اعلام ویژگیها توضیح داده شده است:
VPAID
BidResponse.seatbid.bid.apis روی VPAID_1 یا VPAID_2 تنظیم کنید. برای فرمت JSON، این مقدار میتواند به ترتیب روی 1 یا 2 تنظیم شود.
MRAID
BidResponse.seatbid.bid.apis روی MRAID_1 یا برای فرمت JSON 3 تنظیم کنید.
SIZELESS
BidResponse.seatbid.bid.attr روی RESPONSIVE یا برای فرمت JSON 18 تنظیم کنید.
PLAYABLE
این با تنظیم BidResponse.seatbid.bid.attr روی USER_INTERACTIVE یا 13 برای فرمت JSON نشان داده میشود.
برای توضیح در مورد چگونگی دریافت بازخورد در مورد ویژگیهای شناساییشدهی آثار خلاقانهتان، به منبع Creatives مراجعه کنید.
زمینههای مناقصه آزاد
پاسخهای پیشنهادی ارسال شده توسط پیشنهاددهندگان بورس و شبکه که در مناقصه آزاد شرکت میکنند، مشابه پاسخهای خریداران مجاز شرکتکننده در مناقصه استاندارد در زمان واقعی است. مشتریان مناقصه آزاد میتوانند تعداد کمی فیلد اضافی را مشخص کنند و چند فیلد موجود ممکن است کاربردهای جایگزین داشته باشند. این موارد شامل موارد زیر است:
میدان
جزئیات
BidResponse.imp.pmp.deals.id
شناسه معامله از فضای نام صرافی که با این پیشنهاد مرتبط است و به ناشران گزارش شده است.
BidResponse.seatbid.bid.ext.exchange_deal_type
نوع معاملهای که به ناشران گزارش میشود، و بر نحوه برخورد با معامله در حراج تأثیر میگذارد.
توکن مورد استفاده برای شناسایی اطلاعات خریدار شخص ثالث نهایی در صورتی که صرافی به عنوان پیشنهاد دهنده باز، واسطه باشد. این اطلاعات از خریدار شخص ثالث دریافت میشود و باید بدون تغییر در پاسخ پیشنهاد به گوگل ارسال شود.
توصیهها
اتصالات HTTPS پایدار (که با نامهای "keep-alive" یا "connection reuse" نیز شناخته میشوند) را روی سرورهای خود فعال کنید. حداقل زمان انتظار را روی 10 ثانیه تنظیم کنید - مقادیر بالاتر در بسیاری از موارد مفید هستند. گوگل این موضوع را در طول آزمایشهای اولیه تأخیر برنامه شما تأیید میکند، زیرا Authorized Buyers درخواستها را با سرعت بالایی ارسال میکند و باید از سربار تأخیر ایجاد یک اتصال TCP جداگانه برای هر درخواست جلوگیری کند.
URL ردیابی نمایش را به صورت اختیاری اضافه کنید تا هنگام نمایش نمایش، به جای زمان برنده شدن پیشنهاد دهنده، ردیابی شود. به دلیل افت بین برنده شدن و نمایش، این امر آمار ردیابی دقیقتری را ارائه میدهد.
کد پیشنهاد دهنده خود را از وابستگی به فیلدهای منسوخ شده که میتواند باعث شکست پیشنهادات شما با خطا شود، دور نگه دارید.
BidResponse.seatbid.bid.w و BidResponse.seatbid.bid.h را در BidResponse خود وارد کنید. یک BidResponse برای درخواستی که شامل چندین اندازه تبلیغ است باید این فیلدها را داشته باشد، در غیر این صورت از مزایده حذف خواهد شد.
اندازه پاسخ خود را به کمتر از 8K محدود کنید. پاسخهای بسیار بزرگ ممکن است تأخیر شبکه را افزایش داده و باعث وقفه شوند.
مهم: پیامهای Protobuf که در نمونهها نشان داده شدهاند، در اینجا به صورت متن قابل خواندن توسط انسان نمایش داده میشوند. با این حال، این نحوه ارسال پیامها از طریق سیم نیست. هنگام استفاده از فرمت OpenRTB Protobuf، فقط پیامهای سریالی BidResponse پذیرفته میشوند.
شما میتوانید با استفاده از کد ++C زیر، یک پیام BidResponse ایجاد و آن را سریالایز کنید:
BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
// respond to the POST with post_response as the content
} else {
// return an error to the POST
}
خلاقیت را مشخص کنید
پاسخ پیشنهاد شما، طرح تبلیغاتی که در صورت برنده شدن پیشنهادتان نمایش داده میشود را مشخص میکند. پیشنهاد شما باید شامل یکی از قالبهای تبلیغاتی پشتیبانیشده (AMP، ویدیو، بومی) باشد. در این مثال، طرح تبلیغاتی را با استفاده از فیلد html_snippet مشخص میکنیم.
از طرف دیگر، میتوانید خلاقیت خود را با استفاده از یکی از فیلدهای زیر، بر اساس قالب تبلیغ، مشخص کنید:
تبلیغ رندر شده توسط SDK
BidResponse.seatbid.bid.ext.sdk_rendered_ad
آمپر
BidResponse.seatbid.bid.amp_ad_url
ویدئو
BidResponse.seatbid.bid.adm
بومی
BidResponse.seatbid.bid.adm_native
با استفاده از یک قطعه کد HTML در فیلد BidResponse.seatbid.bid.adm ، تبلیغی را که روی سرور(های) خودتان میزبانی میشود، مشخص کنید. این قطعه کد در یک iFrame که در صفحه وب قرار داده شده است، محصور شده و در نتیجه تبلیغ هنگام بارگذاری صفحه بازیابی و رندر میشود. شما باید قطعه کد HTML را طوری تنظیم کنید که تبلیغ (بنر یا بینابینی) به درستی در داخل یک iFrame و با اندازه مناسب برای جایگاه تبلیغاتی که در آن پیشنهاد میدهید، رندر شود.
علاوه بر این، اندازه آگهی اعلام شده در پاسخ پیشنهاد باید دقیقاً با یکی از ترکیبهای اندازه در درخواست پیشنهاد مطابقت داشته باشد، زمانی که:
منظور از تبلیغ، یک بنر معمولی است (نه ویدیویی، بومی یا بینابینی).
پیشنهاد دهنده اندازه را در پاسخ پیشنهاد اعلام کرده است. هر زمان که بیش از یک اندازه در درخواست وجود داشته باشد، اعلام اندازه الزامی است.
برای تبلیغات بینابینی یک استثنا وجود دارد. برای تبلیغات بینابینی، عرض باید حداقل ۵۰٪ عرض صفحه نمایش و ارتفاع آن حداقل ۴۰٪ ارتفاع صفحه نمایش باشد.
شما میتوانید با استفاده از هر کد HTML معتبری که به درستی رندر میشود، یک قطعه کد HTML خلاقانه مشخص کنید، اما محدودیتهای مشخص کردن فیلد crid در بخش پیام Create BidResponse را در نظر داشته باشید. یکی از کاربردهای این کار، قرار دادن اطلاعات اضافی در آرگومانهای URLهایی است که به عنوان بخشی از رندر تبلیغ از سرورهای شما دریافت میشوند. این به شما امکان میدهد دادههای دلخواه در مورد نمایش را به سرورهای خود منتقل کنید.
ماکروها متن قالببندیشدهای هستند که در برخی از فیلدهای پاسخ پیشنهاد قیمت جاسازی شدهاند و حاوی URLهایی هستند که در زمان نمایش تبلیغ با مقداری مرتبط جایگزین میشوند. برای مثال، اگر پیشنهاد برنده شما شامل ماکروی AUCTION_PRICE در قطعه کد HTML ارائه شده به همراه پیشنهاد شما باشد، ماکرو با مقداری جایگزین میشود که میتوانید آن را رمزگشایی کنید تا مبلغی را که برای نمایش در حراج پرداخت کردهاید، تعیین کنید.
شما میتوانید ماکروها را در فیلدهای زیر وارد کنید:
BidResponse.seatbid.bid.adm
ماکروها برای قالبهای HTML snippet، native، video URL و video VAST XML پشتیبانی میشوند.
اگر به بیش از یک آدرس اینترنتی پرداخت نیاز دارید، از این به جای BidResponse.seatbid.bid.burl استفاده کنید.
به عنوان مثال، میتوانید با جاسازی ${MACRO} در URL مورد استفاده برای دریافت فایل خلاق، یک ماکرو را به عنوان بخشی از یک قطعه کد HTML وارد کنید، که در آن MACRO یکی از ماکروهای پشتیبانی شدهای است که در مشخصات OpenRTB شرح داده شده است.
ماکروهای گوگل
گوگل علاوه بر مواردی که در مشخصات OpenRTB یافت میشود، از ماکروهای دیگری نیز پشتیبانی میکند. این ماکروها فرمت متفاوتی دارند و اگر در یک URL جاسازی شوند، به صورت %%MACRO%% نمایش داده میشوند. جدول زیر این ماکروها را شرح میدهد:
ماکرو
توضیحات
ADVERTISING_IDENTIFIER
به خریداران اجازه میدهد تا شناسه تبلیغات iOS IDFA یا Android را در هنگام نمایش تبلیغات دریافت کنند. برای جزئیات بیشتر به رمزگشایی شناسههای تبلیغکننده مراجعه کنید.
CACHEBUSTER
نمایش رشتهای از یک عدد صحیح تصادفی، بدون علامت و چهار بایتی.
CLICK_URL_UNESC
آدرس کلیک بدون اسکیپ برای تبلیغ. در قطعه کد، یک نسخه اسکیپ شده از آدرس کلیک شخص ثالث باید مستقیماً پس از ماکرو قرار گیرد.
برای مثال، اگر آدرس کلیک شخص ثالث http://my.adserver.com/some/path/handleclick?click=clk باشد، میتوان از کد زیر با نسخه single-escaped آدرس کلیک شخص ثالث پس از فراخوانی ماکرو استفاده کرد:
این URL ابتدا کلیک را در گوگل ثبت میکند و سپس به URL کلیک شخص ثالث هدایت میشود.
CLICK_URL_ESC
آدرس کلیکِ escape شده برای تبلیغ. اگر نیاز دارید که ابتدا مقدار را از طریق سرور دیگری ارسال کنید که سپس یک ریدایرکت را برمیگرداند، از این به جای CLICK_URL_UNESC استفاده کنید.
برای مثال، کد زیر میتواند در یک قطعه کد HTML استفاده شود:
این کار کلیک را در my.adserver.com ثبت میکند که سپس مسئول هدایت به URL ارسالی در پارامتر google_click_url خواهد بود. این فرض میکند که my.adserver.com پارامتر google_click_url از حالت فشرده خارج میکند.
میتوانید یک URL با دوبار escape شدن بعد از %%CLICK_URL_ESC%% اضافه کنید. پس از اینکه unescaping توسط my.adserver.com انجام شد، یک نسخه single-escaped از URL باقی میماند که به google_click_url اضافه شده است. وقتی google_click_url دریافت میشود، یک بار دیگر unscape شده و سپس تغییر مسیر میدهد.
CLICK_URL_ESC_ESC
آدرس اینترنتی (URL) تبلیغ که با دو بار escape شدن نمایش داده میشود. اگر نیاز دارید که ابتدا مقدار را از طریق سرور دیگری ارسال کنید که سپس یک ریدایرکت را برمیگرداند، از این به جای CLICK_URL_UNESC استفاده کنید.
برای مثال، کد زیر میتواند در یک قطعه کد HTML استفاده شود:
اگر درخواست پیشنهاد به SSL نیاز نداشته باشد، به http: و اگر به https: گسترش مییابد.
SITE
دامنهی url-escaped مربوط به URL محتوا یا شناسهی ناشناس برای فهرست ناشناس.
SITE_URL
منسوخ شده. با ماکروی SITE که عملکرد یکسانی را ارائه میدهد، جایگزین شده است.
TZ_OFFSET
انحراف منطقه زمانی.
VERIFICATION
مقادیر مختلف برای تولید و زمانی که طرح در خط لوله تأیید اسکن میشود. قالب به این صورت است: %%?VERIFICATION:true-val:false-val%% که در آن میتوان از هر مقداری به جز ماکروها برای true-val و false-val ، از جمله رشتههای خالی، استفاده کرد. برای پیشنهاد باز، توصیه میکنیم صرافیها از این ماکرو استفاده کنند. پس از انجام این کار، پلتفرمهای سمت تقاضا نیازی به ایجاد تغییر ندارند.
برای مثال، اگر یک متن تبلیغاتی شامل %%?VERIFICATION:-1:5000%% باشد، متن جایگزین در هنگام ارسال 5000 و در هنگام تأیید -1 خواهد بود. این کار برای کمک به تمایز بین این دو مجموعه پینگ انجام میشود.
WINNING_PRICE
هزینه نمایش کدگذاری شده (یعنی CPI به جای CPM) بر حسب میکرو واحد پول حساب. برای مثال، یک CPM برنده ۵ دلار آمریکا معادل ۵،۰۰۰،۰۰۰ میکرو CPM یا ۵،۰۰۰ میکرو CPI است. مقدار رمزگشایی شده WINNING_PRICE در این مورد ۵،۰۰۰ خواهد بود. قیمت برنده بر حسب CPI مشخص شده است.
برای تجزیه این ماکرو، باید برنامهای پیادهسازی کنید که تأییدیههای قیمت را رمزگشایی کند. برای اطلاعات بیشتر به صفحه رمزگشایی تأییدیههای قیمت مراجعه کنید.
WINNING_PRICE_ESC
WINNING_PRICE با URL اسکیپ شده.
گوگل از شما میخواهد که از ماکروهای CLICK_URL_UNESC یا CLICK_URL_ESC در متن آگهی تبلیغاتی شخص ثالث استفاده کنید. گوگل از ماکروهای CLICK_URL برای ردیابی کلیک استفاده میکند.
فرار URL در ماکروها از طرح زیر استفاده میکند:
کاراکتر فاصله (space) با علامت جمع ( + ) جایگزین میشود.
کاراکترهای الفبایی-عددی (0-9، az، AZ) و کاراکترهای مجموعه !()*،-./:_~ بدون تغییر باقی میمانند.
تمام کاراکترهای دیگر با %XX جایگزین میشوند، که در آن XX عدد هگزادسیمال نشان دهنده کاراکتر است.
محدودیتها و الزامات ناشر
درخواست پیشنهاد شامل اطلاعاتی در مورد انواع محدودیتها و الزاماتی است که ناشران برای آثار هنری در حراج اعمال میکنند.
BidRequest.bcat
شما میتوانید دستههای مسدود شده مشخص شده توسط این فیلد را با دستههای شناسایی شده برای آگهیهای تبلیغاتی ارسالی خود با استفاده از فیلد detectedCategories در API پیشنهاد قیمت لحظهای مقایسه کنید.
BidRequest.imp.ext.allowed_vendor_type
BidRequest.imp.secure
در عمل، این همیشه true تنظیم میشود زیرا گوگل برای همه آگهیهای تبلیغاتی به پشتیبانی SSL نیاز دارد.
BidRequest.imp.{audio/banner/native/video}
BidRequest.imp.{audio/banner/native/video}.api
BidRequest.imp.{audio/banner/native/video}.battr
BidRequest.imp.{audio/banner/video}.mimes
هرگز با تبلیغی که حاوی ویژگی محدود شده است، پیشنهاد قیمت ندهید. برای ویژگیهای مجاز مانند نوع فروشنده، فقط در صورتی تبلیغ را برگردانید که نوع فروشنده آن در لیست allowed_vendor_type در BidRequest باشد. فقط قالبهای تبلیغاتی که در درخواست پیشنهاد با پر کردن فیلدهایی مانند BidRequest.imp.banner مشخص شدهاند، باید در پیشنهاد شما گنجانده شوند. برای جزئیات بیشتر، به توضیحات مربوط به این فیلدها در تعریف بافر پروتکل BidRequest مراجعه کنید.
اگر تبلیغی در BidResponse برگردانده شود، شما ملزم به تنظیم دقیق فیلدهای BidResponse.seatbid.bid.attr ، BidResponse.seatbid.bid.cat و یا BidResponse.seatbid.bid.adomain یا BidResponse.seatbid.bid.adm_native.link.url در BidResponse هستید. اگر یک تبلیغ چندین مقدار قابل اجرا برای این فیلدها دارد، باید هر مقدار را وارد کنید. برای جزئیات بیشتر به توضیحات مربوط به این فیلدها در تعریف بافر پروتکل BidResponse مراجعه کنید. پاسخهایی که این فیلدها را تنظیم نکرده باشند، نادیده گرفته میشوند.
اندازهگیری باز
ابزار اندازهگیری باز به شما امکان میدهد فروشندگان شخص ثالثی را مشخص کنید که خدمات اندازهگیری و تأیید مستقلی را برای تبلیغات ارائه شده در محیطهای برنامههای تلفن همراه ارائه میدهند.
قالبهای تبلیغاتی پشتیبانیشده شامل ویدئو، بنر و تبلیغات بینابینی است. برای اطلاعات بیشتر در مورد نحوه استفاده از Open Measurement در یک پاسخ پیشنهاد شامل این قالبها، به مقاله مرکز راهنمای Open Measurement SDK مراجعه کنید.
نمونه پاسخهای پیشنهاد قیمت
بخشهای زیر نمونههایی از پاسخهای پیشنهادی برای انواع مختلف تبلیغات را نشان میدهند.
id:"550102L8So5v6gi4C00T36"seatbid{bid{id:"U796oSA426V3U666ue8"impid:"1"price:1.057860016822815crid:"test_creative_id_395811"dealid:"0"adm_native{ver:"1.2"assets{id:6img{url:"https://native.test.com/logo?id=123456"w:200h:200type:LOGO}}assets{id:5img{url:"https://native.test.com/image?id=123456"w:800h:800type:MAIN}}assets{id:4data{value:"Galactic Luxury Cruises"type:SPONSORED}}assets{id:3data{value:"Book today"type:CTATEXT}}assets{id:1title{text:"Luxury Mars Cruises"}}assets{id:2data{value:"Visit the planet in a luxury spaceship."type:DESC}}link{url:"https://www.google.com"}}[com.google.doubleclick.bid]{impression_tracking_url:"https://test.com/impression?id=123456"impression_tracking_url:"https://test.com/impression?id=123456"ad_choices_destination_url:"https://test.com/preferences"event_notification_token{payload:"token"}billing_id:73917825312dsa{adrender:true}clickurl:"google.com"}}}cur:"JPY"[com.google.doubleclick.bid_response]{processing_time_ms:17}
OpenRTB JSON
مثال را به من نشان بده
{"id":"550102L8So5v6gi4C00T36","seatbid":[{"bid":[{"id":"U796oSA426V3U666ue8","impid":"1","price":1.057860016822815,"crid":"test_creative_id_395811","dealid":"0","ext":{"impression_tracking_url":["https://test.com/impression?id=123456","https://test.com/impression?id=123456"],"ad_choices_destination_url":"https://test.com/preferences","event_notification_token":{"payload":"token"},"billing_id":"73917825312","dsa":{"adrender":1},"clickurl":["google.com"]},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":6,\"img\":{\"url\":\"https://native.test.com/logo?id=123456\",\"w\":200,\"h\":200,\"type\":2}},{\"id\":5,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":800,\"h\":800,\"type\":3}},{\"id\":4,\"data\":{\"value\":\"Galactic Luxury Cruises\",\"type\":1}},{\"id\":3,\"data\":{\"value\":\"Book today\",\"type\":12}},{\"id\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\",\"type\":2}}],\"link\":{\"url\":\"https://www.google.com\"}}"}]}],"cur":"JPY","ext":{"processing_time_ms":17}}
تاریخ آخرین بهروزرسانی 2026-02-23 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2026-02-23 بهوقت ساعت هماهنگ جهانی."],[],["Applications must respond to each `BidRequest` with a parsable `BidResponse`, using Protobuf or an HTTP 204 for no bids. Creatives are identified by a unique `crid`. Ad attributes, such as VPAID and MRAID, are declared in specific fields. Utilize impression tracking URLs and avoid deprecated fields. Open Bidding bid responses are similar to Authorized Buyers. Ad sizes in the response must match the request. Macros are used in URLs. Publisher requirements are specified in the `BidRequest`. The response must accurately reflect these requirements and provide the accurate ad attributes and links.\n"]]
