راهنمای فروشنده: حراج های تبلیغاتی را اجرا کنید

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

در این مقاله، یک مرجع فنی برای حراج تبلیغات، همانطور که در نسخه فعلی API آزمایشی Protected Audience استفاده می‌شود، خواهید یافت.

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

توسعه‌دهنده نیستید؟ به مرور کلی API مخاطبان محافظت‌شده مراجعه کنید.

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

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

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

مزایده چه زمانی برگزار می‌شود؟

API مخاطب محافظت‌شده می‌تواند به تنهایی یا با مزایده‌های برنامه‌ریزی‌شده اجرا شود. در یک مزایده برنامه‌ریزی‌شده چندفروشنده‌ای:

1. کاربر از یک سایت شرکت‌کننده بازدید می‌کند.
2. یک حراج برنامه‌ریزی‌شده توسط فروشنده دیگری اجرا می‌شود تا یک تبلیغ زمینه‌ای برای یک جایگاه تبلیغاتی موجود پیدا کند.
3. حراج API مخاطبان محافظت‌شده اجرا می‌شود.
4. scoreAd() پیشنهادهای خریدار را با نتایج حراج اول مقایسه می‌کند.

پیشنهادهایی که نتوانند برنده‌ی زمینه‌ای را شکست دهند، رد می‌شوند.

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

چندین طرف وجود دارند که ممکن است برای فروش فضای تبلیغاتی، حراج برگزار کنند.

برای مثال:

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

با استفاده از API مخاطبان محافظت‌شده، یک فروشنده سه وظیفه دارد:

• قوانین ناشر را اجرا کنید: کدام خریداران و کدام پیشنهادها واجد شرایط هستند.
• منطق اجرای مزایده: جاوا اسکریپت در workletها اجرا می‌شود تا امتیاز مطلوبیت برای هر پیشنهاد محاسبه شود.
• نتیجه مزایده را گزارش دهید.

این کارها به صورت برنامه‌نویسی‌شده و در کدی که فروشنده هنگام شروع حراج آگهی با فراخوانی تابع جاوااسکریپت navigator.runAdAuction() ارائه می‌دهد، انجام می‌شوند.

توابع API

runAdAuction()

فروشنده با فراخوانی تابع navigator.runAdAuction() از مرورگر کاربر درخواست می‌کند تا حراج تبلیغات را آغاز کند.

برای مثال:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() یک promise را برمی‌گرداند که به یک URN ( urn:uuid:<something> ) تبدیل می‌شود که نشان‌دهنده‌ی نتیجه‌ی مزایده‌ی آگهی است. این خروجی فقط زمانی توسط مرورگر قابل رمزگشایی است که برای رندر شدن به یک قاب محصور (fenced frame) ارسال شود: صفحه‌ی ناشر نمی‌تواند آگهی برنده را بررسی کند.

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

ویژگی‌های auctionConfig

seller

مورد نیاز

مثال: 'https://ssp.example'

نقش: خاستگاه فروشنده.

decisionLogicUrl

مورد نیاز

مثال: 'https://ssp.example/auction-decision-logic.js'

نقش: آدرس اینترنتی برای کتابچه حراج جاوا اسکریپت.

trustedScoringSignalsUrl

اختیاری

مثال: 'https://ssp.example/scoring-signals'

نقش: آدرس اینترنتی سرور مورد اعتماد فروشنده.

interestGroupBuyers

مورد نیاز

مثال: ['https://dsp.example', 'https://buyer2.example', ...]

نقش: خاستگاه تمام مالکان گروه‌های ذینفع که از آنها خواسته شده در حراج پیشنهاد قیمت بدهند.

نکات: فروشنده ممکن است interestGroupBuyers: را مشخص کند تا به همه گروه‌های ذینفع اجازه پیشنهاد قیمت بدهد. سپس تبلیغات بر اساس معیارهایی غیر از شمول صاحب گروه ذینفع پذیرفته یا رد می‌شوند. به عنوان مثال، فروشنده ممکن است آگهی‌های تبلیغاتی را برای تأیید انطباق با سیاست‌های خود بررسی کند.

auctionSignals

اختیاری

مثال: {...}

نقش: اطلاعات فروشنده در مورد زمینه صفحه، نوع حراج و غیره.

sellerSignals

اختیاری

مثال: {...}

نقش: اطلاعات مبتنی بر تنظیمات ناشر، درخواست تبلیغات زمینه‌ای و غیره.

sellerTimeout

اختیاری

مثال: 100

نقش: حداکثر زمان اجرا (میلی‌ثانیه) اسکریپت scoreAd() فروشنده.

perBuyerSignals

اختیاری

مثال:

{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }

نقش: سیگنال‌های زمینه‌ای در مورد صفحه برای هر خریدار خاص، از سرور آنها.

perBuyerTimeouts

اختیاری

مثال: 50

نقش: حداکثر زمان اجرا (میلی‌ثانیه) اسکریپت‌های generateBid() خریدار خاص.

componentAuctions

اختیاری

مثال:

[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]

نقش: تنظیمات اضافی برای حراج قطعات .

decisionLogicUrl

decisionLogicUrl یک ویژگی از شیء پیکربندی حراج است که به runAdAuction() ارسال می‌شود. این URL باید شامل یک اسکریپت برای تابع scoreAd() باشد. این منطق برای هر تبلیغ یک بار اجرا می‌شود تا مطلوبیت آن تعیین شود.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

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

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

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

scoreAd()

scoreAd() آرگومان‌های زیر را دریافت می‌کند:

سوالات متداول

برنده مزایده چگونه تعیین می‌شود و چه کسی او را انتخاب می‌کند؟

فروشنده منطق امتیازدهی را برای تعیین امتیاز مطلوبیت هر تبلیغ ارائه می‌دهد و مرورگر بالاترین امتیاز را به عنوان تبلیغ برنده انتخاب می‌کند.

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

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

راهنماهای مرجع API در دسترس هستند:

• راهنمای برنامه‌نویس برای API مخاطبان محافظت‌شده .
• راهنمای خرید آگهی برای گروه‌های ذینفع مخاطب محافظت‌شده و تولید پیشنهاد .
• راهنمای فروشنده آگهی برای مزایده تبلیغات مخاطب محافظت شده.
• راهنمای گزارش نتایج مزایده
• بهترین روش‌ها برای تأخیر حراج تبلیغات مخاطب محافظت‌شده
• عیب یابی مخاطب محافظت شده

توضیح دهنده Protected Audience API همچنین جزئیاتی در مورد پشتیبانی از ویژگی ها و محدودیت ها ارائه می دهد.