דיווח על תוצאות מכרזים של Protected Audience API

מדריך לספקים ולקנייני מדיה ליצירת דוחות על מכרזים של Protected Audience API.

המאמר הזה הוא הפניה טכנית ליצירת דוחות על זכיות במכרזים של Protected Audience API, כפי שנעשה בגרסה הנוכחית של Protected Audience API הניסיוני.

במדריך למפתחים מוסבר על מחזור החיים המלא של Protected Audience API. במאמר ההסבר על Protected Audience API יש דיון מעמיק על דוחות ברמת האירוע (זמני).

אתם לא מפתחים? מידע נוסף מופיע בסקירה הכללית על Protected Audience API.

מה מדווח ב-Protected Audience API?

יש שני דוחות זמינים של Protected Audience API:

• דוח לבית העסק: בדוח הזה מודיעים לבית העסק מי הזוכה במכרז על שטחי הפרסום.
• דוח קונים: זמין רק לקונים שזכו במכרז, כדי לדעת שהם זכו במכרז.

התוכנית לטווח הארוך היא לאפשר לדפדפן לדווח על תוצאות המכרז למוכר ולרוכשים באמצעות ממשקי ה-API של Private Aggregation API. כמנגנון דיווח זמני ברמת האירוע, הקוד שמטמיע את reportResult() עבור המוכר ואת reportWin() עבור המציע שזכה יכול לקרוא לפונקציה sendReportTo(). הפונקציה מקבלת ארגומנט יחיד: מחרוזת שמייצגת כתובת URL שאליה מתבצעת אחזור אחרי שהמכרז מסתיים, שמקודדת מידע ברמת האירוע לדיווח.

פונקציות API

המוכר: reportResult()

קוד ה-JavaScript של המוכר שמופיע ב-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()

קוד ה-JavaScript של המשתתף שהצעת המחיר שלו זכתה (שסיפק גם את 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>
}

הטמעה זמנית של דיווח

יש שתי שיטות זמינות באופן זמני ב-Chrome לדיווח על מכרזים:

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

כל אחת מהשיטות האלה מקבלת ארגומנט יחיד: כתובת URL לאחזור אחרי שהמכרז מסתיים. אפשר לקרוא להן כמה פעמים, גם ב-scoreAd() וגם ב-generateBid(), עם ארגומנטים שונים של כתובות URL.

‫Chrome שולח דוחות ניפוי באגים על הפסדים או זכיות רק כשהמכרז מסתיים. אם מכרז מבוטל (לדוגמה, בגלל ניווט חדש), לא יופקו דוחות.

השיטות האלה זמינות כברירת מחדל ב-Chrome כשמפעילים את כל ממשקי ה-API לשמירה על הפרטיות בפרסום בקטע chrome://settings/adPrivacy. אם אתם מפעילים את Chrome עם פקודות שורת פקודות כדי להפעיל את Protected Audience API, תצטרכו להפעיל את השיטות באופן מפורש על ידי הוספת הדגל BiddingAndScoringDebugReportingAPI. אם הדגל לא מופעל, השיטות עדיין יהיו זמינות אבל לא יעשו כלום.

כל ההפניות ל-Protected Audience 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.