این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

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

برنامه بلندمدت این است که به مرورگر اجازه می‌دهد نتایج حراج را برای فروشنده و خریداران با APIهای API Aggregation خصوصی گزارش کند. به عنوان یک مکانیسم گزارش موقت در سطح رویداد، کد پیاده‌سازی 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) {
  ...
}

توجه: اجرای فعلی Protected Audience API در کروم در صورتی که reportWin() تعریف نشده باشد هشدار می دهد.

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

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>
}

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

دو روش به طور موقت در Chrome برای گزارش حراج در دسترس است:

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

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

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

اگر chrome://flags/#privacy-sandbox-ads-apis فعال باشد، این روش‌ها به‌طور پیش‌فرض در Chrome در دسترس هستند. اما، اگر Chrome را با پرچم‌های خط فرمان برای فعال کردن API مخاطب محافظت‌شده اجرا می‌کنید، باید صراحتاً روش‌ها را با اضافه کردن پرچم BiddingAndScoringDebugReportingAPI فعال کنید. اگر پرچم فعال نباشد، روش ها همچنان در دسترس خواهند بود اما کاری انجام نمی دهند.

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

API reference guides are available:

Developer guide for the Protected Audience API.
Ad buyer guide to Protected Audience interest groups and bid generation.
Ad seller guide to Protected Audience ad auctions.
Guide to reporting auction results
Best practices for Protected Audience ad auction latency
Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.