מדריך למוכרים ולקונים ליצירת דוחות מכרזים של 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.
- המדריך לקונים של מודעות בנושא קבוצות תחומי עניין ויצירת הצעות מחיר של Protected Audience.
- המדריך למוכר מודעות למכרזי מודעות של Protected Audience.
- מדריך לדיווח על תוצאות מכרזים
- שיטות מומלצות לזמן אחזור של מכרז מודעות עם Protected Audience
- פתרון בעיות ב'קהל מוגן'
הסבר על Protected Audience API כולל גם פרטים על התמיכה בתכונות והאילוצים.
מה השלב הבא?
אנחנו רוצים להיות מעורבים בשיחות כדי לוודא שאנחנו מפתחים API שעובד עבור כולם.
דיון על ה-API
כמו ממשקי API אחרים של ארגז החול לפרטיות, ממשק ה-API הזה מתועד ונושא דיון ציבורי.
התנסות עם ה-API
אתם יכולים לערוך ניסויים ולהשתתף בשיחה על Protected Audience API.