یک حراج مبتنی بر مرورگر را با یک فروشنده اجرا کنید

در این سند، یک مرور کلی سطح بالا برای اجرای یک حراج با داده‌های مخاطب محافظت‌شده برای یک فروشنده واحد، همانطور که در نسخه فعلی API مخاطب محافظت‌شده استفاده می‌شود، خواهید یافت. یک حراج با یک فروشنده واحد می‌تواند به عنوان بخشی از یک حراج پیچیده‌تر شامل چندین فروشنده اجرا شود. در این حالت، حراج یک فروشنده به عنوان "حراج جزء" شناخته می‌شود، که می‌تواند نامزدهای تبلیغاتی را برای "حراج سطح بالا" که چندین فروشنده در آن شرکت دارند، فراهم کند.

برای چرخه کامل عمر Protected Audience API، راهنمای توسعه‌دهنده را مطالعه کنید و برای بحث عمیق‌تر در مورد نحوه اجرای حراج‌های روی دستگاه توسط فروشندگان، به توضیح‌دهنده Protected Audience API مراجعه کنید.

شش مرحله از حراج تبلیغات API مخاطبان محافظت‌شده

1. کاربر از سایتی بازدید می‌کند که تبلیغات را نمایش می‌دهد.
2. کد فروشنده navigator.runAdAuction() را اجرا می‌کند. این تابع مشخص می‌کند که کدام فضای تبلیغاتی برای فروش است و چه کسی می‌تواند پیشنهاد قیمت بدهد. فروشندگان همچنین باید اسکریپتی را که به هر پیشنهاد امتیاز می‌دهد، scoreAd() ، درج کنند.
3. کد خریدار دعوت‌شده اجرا می‌شود تا یک پیشنهاد قیمت، URL برای آگهی تبلیغاتی مرتبط و سایر داده‌ها ایجاد کند. اسکریپت پیشنهاد قیمت می‌تواند داده‌های بلادرنگ، مانند بودجه باقی‌مانده کمپین تبلیغاتی، را از سرویس Key/Value خریدار جستجو کند.
4. کد فروشنده به هر پیشنهاد امتیاز می‌دهد و یک برنده انتخاب می‌کند. این منطق از مقدار پیشنهاد و سایر داده‌ها برای تعیین مطلوبیت یک پیشنهاد استفاده می‌کند. تبلیغاتی که نتوانند برنده‌ی زمینه‌ای را شکست دهند، رد می‌شوند. فروشنده می‌تواند از سرویس کلید/مقدار خود برای داده‌های بلادرنگ استفاده کند.
5. آگهی برنده به صورت یک مقدار مبهم برگردانده می‌شود که در یک قاب محصور نمایش داده می‌شود. هم فروشنده و هم ناشر قادر به مشاهده این مقدار نخواهند بود.
6. حراج به فروشنده و خریداران برنده گزارش می‌شود.

یک مزایده می‌تواند زمانی اتفاق بیفتد که کاربر به صفحه‌ای که یک تبلیغ را نمایش می‌دهد، هدایت شود. مزایده‌ها ممکن است از قبل اجرا شوند تا وقتی که جایگاه تبلیغ ظاهر می‌شود، تبلیغ آماده باشد.

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

فروشنده ممکن است به موارد زیر اشاره داشته باشد:

• ناشران محتوا، که برای خودشان محتوای تبلیغاتی را در وب‌سایتشان میزبانی می‌کنند
• پلتفرم‌های سمت عرضه (SSP)، که با ناشر آگهی همکاری می‌کنند و خدمات دیگری ارائه می‌دهند
• اسکریپت‌های شخص ثالث، که برای ناشران جهت مشارکت در مزایده‌های تبلیغاتی عمل می‌کنند.

شرایط لازم برای برگزاری مزایده

یک فروشنده برای اجرای حراج به دو تابع جاوا اسکریپت نیاز دارد:

• scoreAd() که به یک کاندید تبلیغ امتیاز می‌دهد
• reportResult() که وظیفه گزارش نتیجه حراج به خود فروشنده را بر عهده دارد.

این اسکریپت‌ها باید از یک نقطه پایانی واحد که متعلق به فروشنده است، ارائه شوند.

scoreAd()

یک فروشنده باید یک تابع scoreAd() تعریف کند که از یک نقطه پایانی که متعلق به اوست، ارائه شود. نقطه پایانی در پیکربندی حراج به عنوان decisionLogicUrl مشخص شده است. تابع scoreAd() دارای امضای زیر است:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

پارامترهای scoreAd() عبارتند از:

• adMetaData ، که یک فراداده دلخواه درباره آگهی تبلیغاتی است که توسط خریدار ارائه می‌شود. این یک شیء سریالی‌پذیر JSON است که فروشندگان و خریداران باید آن را تعریف کرده و بر سر ساختار آن به توافق برسند.
• bid ، که یک مقدار عددی است که نشان دهنده پیشنهاد قیمت است.
• auctionConfig ، که پیکربندی حراج مورد استفاده برای اجرای حراج است.
• trustedScoringSignals ، که سیگنال‌هایی هستند که در زمان حراج از سرور Key/Value فروشنده خوانده می‌شوند. پلتفرم از renderUrl تبلیغ کاندید به عنوان کلید این جستجو استفاده خواهد کرد.
• browserSignals ، که یک شیء ساخته شده توسط مرورگر است، شامل اطلاعاتی که مرورگر می‌داند و اسکریپت حراج فروشنده ممکن است بخواهد آنها را تأیید کند.
• directFromSellerSignals شیء‌ای است که ممکن است شامل فیلدهای زیر باشد: ** sellerSignals : مانند auctionConfig.sellerSignals ، اما با استفاده از مکانیزم directFromSellerSignals ارسال می‌شود. ** auctionSignals : مانند auctionConfig.auctionSignals ، اما با استفاده از مکانیزم directFromSellerSignals ارسال می‌شود.

در زیر مثالی از browserSignals آمده است. توجه داشته باشید که renderUrl تبلیغ کاندید از طریق این سیگنال‌ها در دسترس است:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

یک فروشنده باید یک تابع reportResult() تعریف کند که از یک نقطه پایانی که متعلق به اوست، ارائه شود. نقطه پایانی در پیکربندی حراج به عنوان decisionLogicUrl مشخص شده است. تابع reportResult() دارای امضای زیر است:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

پارامترهای reportResult() عبارتند از:

• auctionConfig ، که پیکربندی حراج مورد استفاده برای اجرای حراج است.
• browserSignals ، که یک شیء ساخته شده توسط مرورگر است، شامل اطلاعاتی که مرورگر می‌داند و اسکریپت حراج فروشنده ممکن است بخواهد آنها را تأیید کند. این همان شیء ارسال شده به تابع scoreAds() است.

reportResult() مقدار signalsForWinner برمی‌گرداند که یک شیء JSON دلخواه است و به تابع گزارش‌دهی خریدار برنده ارسال می‌شود. این باید شامل هرگونه اطلاعات مرتبطی باشد که فروشنده می‌تواند در مورد حراج ارائه دهد و خریدار برای گزارش‌دهی خود به آن نیاز دارد.

یک حراج API مخاطب محافظت‌شده اجرا کنید

چهار مرحله اصلی وجود دارد که یک فروشنده باید برای اجرای یک حراج انجام دهد. توجه داشته باشید که این مراحل فرض می‌کنند که فروشنده یک نقطه پایانی برای بازگرداندن جاوا اسکریپت مورد نیاز که قبلاً در این راهنما ذکر شده است، تنظیم کرده است.

1. پیکربندی حراج. این مرحله شامل ایجاد یک شیء auctionConfig است. این به فروشنده امکان می‌دهد مشخص کند کدام خریداران باید در حراج شرکت کنند، و همچنین هرگونه سیگنالی را که ممکن است در طول تولید پیشنهاد یا امتیازدهی به تبلیغات مرتبط باشد، ارائه دهد.
2. با فراخوانی navigator.runAdAuction() و ارسال پیکربندی ایجاد شده در مرحله قبل، حراج را اجرا کنید. این کار زنجیره‌ای از خریداران را آغاز می‌کند که پیشنهاد قیمت می‌دهند و سپس امتیاز می‌دهند. نتیجه نهایی این مرحله، یک کاندید تبلیغ است که می‌تواند برای نمایش یک تبلیغ رندر شود.
3. تبلیغ برنده را در یک قاب یا iframe محصور شده ارائه دهید .
4. نتیجه حراج را گزارش دهید. تابعی به navigator.sendReportTo() وجود دارد که گزارش‌دهی را آغاز می‌کند. فروشنده همیشه گزارشی از نتایج حراج دریافت می‌کند. فقط خریداری که در حراج برنده شده است، گزارش دریافت خواهد کرد. این تابع از reportResult() فروشنده که قبلاً در این راهنما توضیح داده شده است، برای گزارش به سرور خود استفاده می‌کند.