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

בכל אחת מה-methods האלה יש ארגומנט אחד: כתובת 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.