מדריך למוכרים ולקונים ליצירת דוחות מכרזים של 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 reference guides are available:
- Developer guide for the Protected Audience API.
- Ad buyer guide to Protected Audience interest groups and bid generation.
- Ad seller guide to Protected Audience ad auctions.
- Guide to reporting auction results
- Best practices for Protected Audience ad auction latency
- Troubleshoot Protected Audience
The Protected Audience API explainer also provides detail about feature support and constraints.
What's next?
We want to engage in conversations with you to ensure we build an API that works for everyone.
Discuss the API
Like other Privacy Sandbox APIs, this API is documented and discussed publicly.
Experiment with the API
You can experiment and participate in conversation about the Protected Audience API.