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

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

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

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

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

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

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

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

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

Protected Audience API می تواند به تنهایی یا با حراج های برنامه ای اجرا شود. در حراجی چند فروشنده و برنامه ای:

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

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

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

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

مثلا:

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

با استفاده از Protected Audience API، یک فروشنده سه شغل دارد:

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

این کارها به صورت برنامه نویسی انجام می شوند، در کدی که فروشنده هنگام ایجاد حراج تبلیغاتی با فراخوانی تابع JavaScript 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() قولی را برمی‌گرداند که به یک URN ( urn:uuid:<something> ) که نشان‌دهنده نتیجه حراج آگهی است، حل می‌شود. این فقط زمانی می تواند توسط مرورگر رمزگشایی شود که به یک قاب محصور برای رندر منتقل شود: صفحه ناشر نمی تواند آگهی برنده را بازرسی کند.

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

خواص auctionConfig

seller
ضروری
مثال: 'https://ssp.example'
نقش: مبدأ فروشنده.
decisionLogicUrl
ضروری
مثال: 'https://ssp.example/auction-decision-logic.js'
نقش: URL برای Worklet حراج جاوا اسکریپت.
trustedScoringSignalsUrl
اختیاری
مثال: 'https://ssp.example/scoring-signals'
نقش: URL سرور مورد اعتماد فروشنده.
interestGroupBuyers
ضروری
مثال: ['https://dsp.example', 'https://buyer2.example', ...]
نقش: خاستگاه همه صاحبان گروه های ذینفع که از آنها خواسته شده است در حراج پیشنهاد بدهند.
یادداشت ها: فروشنده ممکن است interestGroupBuyers: برای اجازه دادن به همه گروه های ذینفع برای پیشنهاد. سپس آگهی ها بر اساس معیارهایی غیر از درج مالک گروه مورد علاقه پذیرفته یا رد می شوند. به عنوان مثال، فروشنده ممکن است آگهی‌های خلاقانه را بررسی کند تا مطابقت با خط‌مشی‌های آن‌ها را تأیید کند.
auctionSignals
اختیاری
مثال: {...}
نقش: اطلاعات فروشنده در مورد زمینه صفحه، نوع حراج و غیره.
sellerSignals
اختیاری
مثال: {...}
نقش: اطلاعات بر اساس تنظیمات ناشر، ایجاد یک درخواست آگهی متنی و غیره.
sellerTimeout
اختیاری
مثال: 100
نقش: حداکثر زمان اجرا (ms) اسکریپت 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() آرگومان های زیر را می گیرد:

بحث و جدل نقش
adMetadata ابرداده خودسرانه ارائه شده توسط خریدار.
auctionConfig شیء پیکربندی مزایده به navigator.runAdAuction() ارسال شد.
bid یک ارزش پیشنهادی عددی
trustedScoringSignals مقادیر بازیابی شده در زمان حراج از سرور مورد اعتماد فروشنده، نشان دهنده نظر فروشنده در مورد آگهی است.

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

برنده حراج چگونه تعیین می شود و چه کسی آنها را انتخاب می کند؟

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

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

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

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

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