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

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

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

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

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

API مخاطب محافظت‌شده چه چیزی را گزارش می‌دهد؟

دو گزارش API مخاطب محافظت‌شده موجود است:

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

برنامه بلندمدت این است که به مرورگر اجازه داده شود تا نتایج حراج را برای فروشنده و خریداران با APIهای Private Aggregation API گزارش دهد. به عنوان یک مکانیسم گزارش‌دهی موقت در سطح رویداد، کدی reportResult() برای فروشنده و reportWin() را برای پیشنهاددهنده برنده پیاده‌سازی می‌کند، می‌تواند تابع sendReportTo() را فراخوانی کند. این تابع یک آرگومان واحد می‌گیرد: رشته‌ای که نشان دهنده یک URL است که پس از اتمام حراج دریافت می‌شود و اطلاعات سطح رویداد را که باید گزارش شوند، کدگذاری می‌کند.

توابع API

فروشنده: reportResult()

کد جاوا اسکریپت فروشنده که در decisionLogicUrl (که scoreAd() نیز ارائه می‌دهد) ارائه شده است، می‌تواند شامل یک تابع reportResult() باشد تا نتیجه حراج را گزارش دهد.

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

آرگومان‌های ارسالی به این تابع عبارتند از:

auctionConfig

شیء پیکربندی حراج به navigator.runAdAuction() ارسال شد.

browserSignals

یک شیء ساخته شده توسط مرورگر که اطلاعاتی در مورد حراج ارائه می‌دهد. برای مثال:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

مقدار برگشتی این تابع به عنوان آرگومان sellerSignals برای تابع reportWin() ‎ برنده‌ی مزایده استفاده می‌شود.

خریدار: reportWin()

جاوا اسکریپت برنده مزایده (که تابع generateBid() را نیز ارائه می‌دهد) می‌تواند شامل یک تابع reportWin() برای گزارش نتیجه مزایده باشد.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

آرگومان‌های ارسالی به این تابع عبارتند از:

auctionSignals و perBuyerSignals

مقادیر مشابهی برای generateBid() برای پیشنهاد دهنده برنده ارسال شد.

sellerSignals

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

browserSignals

یک شیء ساخته شده توسط مرورگر که اطلاعاتی در مورد حراج ارائه می‌دهد. برای مثال:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

اجرای گزارش موقت

دو روش موقت در کروم برای گزارش حراج وجود دارد:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

هر کدام از این متدها یک آرگومان واحد دریافت می‌کنند: یک URL برای دریافت پس از اتمام حراج. آن‌ها می‌توانند چندین بار، هم در scoreAd() و هم generateBid() ، با آرگومان‌های URL مختلف فراخوانی شوند.

کروم فقط زمانی گزارش‌های اشکال‌زداییِ باخت/برد را ارسال می‌کند که یک حراج به پایان رسیده باشد. اگر حراج لغو شود (مثلاً به دلیل یک ناوبری جدید) هیچ گزارشی ایجاد نخواهد شد.

این روش‌ها به طور پیش‌فرض در کروم در دسترس هستند، زمانی که تمام APIهای حریم خصوصی تبلیغات را در chrome://settings/adPrivacy فعال کنید. اگر کروم را با پرچم‌های خط فرمان برای فعال کردن API مخاطب محافظت‌شده اجرا می‌کنید، باید با اضافه کردن پرچم BiddingAndScoringDebugReportingAPI ، روش‌ها را به طور صریح فعال کنید. اگر این پرچم فعال نباشد، روش‌ها همچنان در دسترس خواهند بود اما کاری انجام نمی‌دهند.

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

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

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

بعدش چی؟

ما می‌خواهیم با شما گفتگو کنیم تا اطمینان حاصل کنیم که یک API درست می‌کنیم که برای همه کار کند.

در مورد API بحث کنید

مانند سایر APIهای Privacy Sandbox، این API مستند شده و به صورت عمومی مورد بحث قرار گرفته است.

با API آزمایش کنید

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