דיווח על תוצאות מכרזים של 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:

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

מה השלב הבא?

אנחנו רוצים להיות מעורבים בשיחות כדי לוודא שאנחנו מפתחים API שעובד עבור כולם.

דיון על ה-API

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

התנסות עם ה-API

אתם יכולים לערוך ניסויים ולהשתתף בשיחה על Protected Audience API.