דיווח על תוצאות מכרזים של 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 אם המדיניות chrome://flags/#privacy-sandbox-ads-apis מופעלת. אבל אם אתם מפעילים את Chrome עם תכונות ניסיוניות בשורת הפקודה כדי להפעיל את Protected Audience API, תצטרכו להפעיל את השיטות באופן מפורש על ידי הכללת הדגל BiddingAndScoringDebugReportingAPI. אם הדגל לא מופעל, השיטות ימשיכו להיות זמינות אבל לא לעשות דבר.

כל ההפניות ל-Protected Audience API

תוכלו להיעזר במדריכים הבאים עם ה-API:

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

מה השלב הבא?

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

דיון על ה-API

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

התנסות עם ה-API

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