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