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

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

עדכון: השם של FLEDGE השתנה ל-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()

הערה: כדאי לקרוא את הסבר על Protected Audience API: דיווח על בתי עסק על רינדור.

קוד ה-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()

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

ה-JavaScript של מגיש הצעות המחיר הזוכה (שגם סיפק ל-generateBid()) יכול כוללים את הפונקציה reportWin() כדי לדווח על תוצאת המכרז.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

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

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

以下是 API 参考指南：

• Protected Audience API 开发者指南。
• 有关 Protected Audience 兴趣群体和出价生成的广告买方指南。
• Protected Audience 广告竞价广告卖方指南。
• 关于报告竞价结果的指南
• Protected Audience 广告竞价延迟时间方面的最佳实践
• 对 Protected Audience 进行问题排查

Protected Audience API 说明信息还详细介绍了功能支持和限制条件。

后续操作

我们希望与您交流，确保我们构建适合所有人的 API。

讨论 API

与其他 Privacy Sandbox API 一样，此 API 也会记录在案并公开讨论。

使用 API 进行实验

您可以进行实验并参与有关 Protected Audience API 的对话。