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