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

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

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

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

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

1. کاربر از سایتی بازدید می کند که تبلیغات را نمایش می دهد.
2. کد فروشنده navigator.runAdAuction() را اجرا می کند. این مشخص می کند که کدام فضای تبلیغاتی برای فروش است و چه کسی می تواند پیشنهاد دهد. فروشندگان همچنین باید یک اسکریپت که هر پیشنهاد را امتیاز می دهد، scoreAd() داشته باشند.
3. کد خریدار دعوت‌شده برای ایجاد پیشنهاد، نشانی وب برای یک آگهی تبلیغاتی مرتبط و سایر داده‌ها اجرا می‌شود. اسکریپت مناقصه می‌تواند داده‌های بی‌درنگ، مانند بودجه کمپین تبلیغاتی باقی‌مانده، را از سرویس کلید/ارزش خریدار جستجو کند.
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 ، سیگنال هایی هستند که در زمان حراج از سرور کلید/ارزش فروشنده خوانده می شوند. پلتفرم از 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() فروشنده که قبلاً در این راهنما توضیح داده شد استفاده می‌کند.