מדריך לממשקי API של בית העסק והפניות למכרז של מודעות Protected Audience API.
במאמר הזה תמצאו חומר עזר טכני בנוגע למכרז של מודעות, כפי שנעשה בו שימוש בגרסה הנוכחית של Protected Audience API הניסיוני.
מומלץ לקרוא את המדריך למפתחים לקבלת מידע על מחזור החיים המלא של Protected Audience API, ולקרוא את ההסבר של Protected Audience API כדי לקרוא הסבר מעמיק על המוכרים מפעילים מכרזים במכשיר.
אינכם מפתחים? אפשר לקרוא את המאמר סקירה כללית על Protected Audience API.
מהי מכרז של מודעות Protected Audience API?
מכרז של מודעות Protected Audience API הוא אוסף של תוכניות JavaScript קטנות שהדפדפן מפעיל במכשיר של המשתמש כדי לבחור מודעה. כדי לשמור על הפרטיות, כל קוד המכרז של המודעות מהמוכר ומהקונים פועלים ברכיבי worklet של JavaScript מבודדים שלא יכולים לתקשר עם העולם שבחוץ.
![שישה שלבים במכרז המודעות של Protected Audience API](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=1&hl=he)
- משתמש מבקר באתר שמוצגות בו מודעות.
- קוד המפיץ מבצע את הפעולה
navigator.runAdAuction()
. מציין איזה שטח להצגת מודעות עומד למכירה ומי יכול להגיש הצעות מחיר. המפיצים גם צריכים לכלול סקריפט שמדרג כל הצעת מחיר,scoreAd()
. - הקוד של הקונה שהוזמן פועל כדי ליצור הצעת מחיר, כתובת URL לקריאייטיב רלוונטי של המודעה ונתונים נוספים. סקריפט הבידינג יכול לבצע שאילתה כדי לקבל נתונים בזמן אמת, כמו התקציב הנותר של קמפיין הפרסום, משירות המפתח/ערך של הקונה.
- הקוד של בית העסק נותן ניקוד לכל הצעת מחיר ובוחר זוכה. הלוגיקה הזו משתמשת בערך הצעת המחיר, ונתונים אחרים מחזירים את הערך הרצוי של הצעת המחיר. מודעות שלא יכולות לגבור על המנצח לפי ההקשר נדחות. המוכרים יכולים להשתמש בשירות מפתחות/ערך משלו לנתונים בזמן אמת.
- המודעה הזוכה מוחזרת כערך אטום שמוצג במסגרת מוגדרת. גם המוכר וגם בעל האתר לא יוכלו לראות את הערך הזה.
- המכרז מדווח למוכר ולקונים שזכו.
מתי מתקיים המכרז?
אפשר להפעיל את Protected Audience API בפני עצמו או במכרזים פרוגרמטיים. במכרז פרוגרמטי עם כמה אתרי מכירה:
- המשתמש מבקר באתר שמשתתף בתוכנית.
- מכרז פרוגרמטי מופעל על ידי אתר מכירה אחר כדי למצוא מודעה לפי הקשר למיקום מודעה זמין.
- המכרז של Protected Audience API פועל.
scoreAd()
משווה בין הצעות המחיר של הקונה לתוצאות של המכרז הראשון.
הצעות מחיר שלא יכולות לגבור על הזוכה לפי הקשר נדחות.
מי מפעיל את מכרז המודעות של Protected Audience API?
יש כמה גורמים שעשויים לנהל מכרז כדי למכור שטח להצגת מודעות.
לדוגמה:
- בעל תוכן דיגיטלי: פועל בשם עצמו לאירוח תוכן מודעות באתר שלו.
- פלטפורמה בצד האספקה (SSP): עבודה עם בעל התוכן הדיגיטלי ומתן שירותים אחרים.
- סקריפט של צד שלישי: פועל מטעם בעל התוכן הדיגיטלי כדי לאפשר השתתפות במכרזי מודעות.
למפיץ Protected Audience API, יש שלוש משימות:
- אכיפת כללים של בעלי תוכן דיגיטלי: אילו קונים ואילו הצעות מחיר כשירים.
- הפעלת לוגיקת מכרז: JavaScript פועל בפלטפורמות עבודה על מנת לחשב את ציון הרצוי לכל הצעת מחיר.
- מדווחים על תוצאת המכרז.
המשימות האלה מתבצעות באופן פרוגרמטי, בקוד שמסופק על ידי בית העסק כשהוא מפעיל מכרז של מודעות על ידי קריאה לפונקציית JavaScript navigator.runAdAuction()
.
פונקציות API
runAdAuction()
המפיץ מגיש בקשה לדפדפן של המשתמש להתחיל מכרז של מודעות על ידי קריאה ל-navigator.runAdAuction()
.
לדוגמה:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
הפונקציה runAdAuction()
מחזירה הבטחה שתואמת ל-URN (urn:uuid:<something>
) שמייצג את תוצאת המכרז של המודעה. אפשר לפענח את ההצפנה על ידי הדפדפן רק כשמעבירים אותה למסגרת מגודרת לצורך רינדור: הדף של בעל האתר לא יכול לבדוק את המודעה הזוכה.
הסקריפט decisionLogicUrl
מתייחס לכל מודעה בודדת, יחד עם הצעת המחיר והמטא-נתונים המשויכים אליה, בזו אחר זו, ואז מקצה למודעה ציון מספרי של מבוקשות.
auctionConfig
מלונות
seller
- חובה
- דוגמה:
'https://ssp.example'
- תפקיד: מקור אתר המכירה.
decisionLogicUrl
- חובה
- דוגמה:
'https://ssp.example/auction-decision-logic.js'
- תפקיד: כתובת URL ל-JavaScript של worklet במכרזים.
trustedScoringSignalsUrl
- אופציונלי
- דוגמה:
'https://ssp.example/scoring-signals'
- תפקיד: כתובת URL של השרת המהימן של אתר המכירה.
interestGroupBuyers
- חובה
- דוגמה:
['https://dsp.example', 'https://buyer2.example', ...]
- התפקיד: המקור של כל הבעלים של קבוצות תחומי עניין שהתבקשו להגיש הצעות מחיר במכרז.
- הערות: בית העסק יכול לציין
interestGroupBuyers:
כדי לאפשר לכל קבוצות האינטרס להגיש הצעות מחיר. לאחר מכן, המודעות מתקבלות או נדחות על סמך קריטריונים אחרים מלבד הכללת הבעלים של קבוצת תחומי העניין. לדוגמה, המפיץ עשוי לבדוק את הקריאייטיבים של המודעות כדי לוודא שהן תואמות למדיניות שלו. auctionSignals
- אופציונלי
- דוגמה:
{...}
- תפקיד: מידע על בית העסק לגבי הקשר הדף, סוג המכרז וכו'.
sellerSignals
- אופציונלי
- דוגמה:
{...}
- תפקיד: מידע שמבוסס על הגדרות של בעל תוכן דיגיטלי, שליחת בקשה לפי הקשר להצגת מודעה וכו'.
sellerTimeout
- אופציונלי
- דוגמה:
100
- תפקיד: זמן ריצה מקסימלי (באלפיות שנייה) של הסקריפט
scoreAd()
של בית העסק. perBuyerSignals
- אופציונלי
- דוגמה:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- תפקיד: אותות לפי הקשר לגבי הדף של כל קונה ספציפי, מהשרת שלו.
perBuyerTimeouts
- אופציונלי
- דוגמה:
50
- תפקיד: זמן ריצה מקסימלי (ms) של סקריפטים מסוימים ב-
generateBid()
של קונה ספציפי. componentAuctions
- אופציונלי
- דוגמה:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- תפקיד: הגדרות נוספות למכרזים רכיבים.
decisionLogicUrl
decisionLogicUrl
הוא מאפיין של אובייקט ההגדרה של המכרז, שמועבר אל runAdAuction()
. כתובת ה-URL הזו חייבת לכלול סקריפט של הפונקציה scoreAd()
. הלוגיקה הזו מופעלת פעם אחת עבור כל מודעה כדי לקבוע מה המודעה הרצויה.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
הוא אובייקט שנבנה על ידי הדפדפן, כולל מידע שהדפדפן מכיר ואיזה סקריפט המכרז של בית העסק עשוי לאמת:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
לפני שהמכרז מתחיל, המפיץ מוצא את המודעה הטובה ביותר לפי הקשר למיקום המודעה הזמין. חלק מהלוגיקה של scoreAd()
דוחה כל מודעה שלא יכולה להשיג את
המנצחת לפי ההקשר.
scoreAd()
הפונקציה scoreAd()
משתמשת בארגומנטים הבאים:
ארגומנט | תפקיד |
---|---|
adMetadata |
מטא-נתונים שרירותיים שסופקו על ידי הקונה. |
auctionConfig |
אובייקט הגדרת המכרז הועבר אל navigator.runAdAuction() . |
bid |
ערך מספרי של הצעת מחיר. |
trustedScoringSignals |
ערכים שאוחזרו בזמן המכרז מהשרת המהימן של המפיץ, שמייצגים את הדעה של המפיץ על המודעה. |
שאלות נפוצות
איך נקבע הזוכה במכרז, ומי בוחר אותו?
בית העסק מספק את לוגיקת הציון כדי לקבוע את ציון רצוי של כל מודעה, והדפדפן בוחר את הציון הגבוה ביותר כמודעה הזוכה.
בית העסק כולל לוגיקה בפונקציה scoreAd()
, והדפדפן מפעיל את הפונקציה ב-worklet שיש בו תקשורת מוגבלת עם קוד מחוץ לו. הדפדפן עצמו לא מדרג את המודעות. רק הדפדפן אחראי לביצוע לוגיקת הציון ולבחור את הצעת המחיר עם הציון הגבוה ביותר.
כל ההפניות ל-Protected Audience API
תוכלו להיעזר במדריכים הבאים עם ה-API:
- מדריך למפתחים של Protected Audience API.
- המדריך לקונים של מודעות בנושא קבוצות תחומי עניין ויצירת הצעות מחיר של Protected Audience.
- המדריך למוכר מודעות למכרזי מודעות של Protected Audience.
- מדריך לדיווח על תוצאות מכרזים
- שיטות מומלצות לזמן אחזור של מכרז מודעות עם Protected Audience
- פתרון בעיות ב'קהל מוגן'
הסבר על Protected Audience API כולל גם פרטים על התמיכה בתכונות והאילוצים.