הפעלת מכרז שמבוסס על דפדפן עם אתר מכירה יחיד

במסמך הזה מוצגת סקירה כללית ברמה גבוהה להפעלת מכרז עם נתוני Protected Audience של אתר מכירה יחיד, כפי שנעשה בגרסה הנוכחית של Protected Audience API. מכרז עם אתר מכירה אחד יכול להתבצע כחלק ממכרז מורכב יותר שכולל כמה אתרי מכירה. במקרה כזה, המכירה הפומבית של אתר מכירה יחיד נקראת 'מכרז רכיבים', שיכול להציג מועמדים להצגת מודעות ב'מכרז ברמה העליונה' שבו משתתפים כמה אתרי מכירה.

קראו את המדריך למפתחים לקבלת מידע על מחזור החיים המלא של Protected Audience API, ועיינו בהסבר של Protected Audience API כדי לקבל הסבר מפורט על האופן שבו מוכרים מנהלים מכרזים במכשיר.

שישה שלבים במכרז המודעות של Protected Audience API

בתרשים הזה מפורט כל שלב במכרז המודעות של Protected Audience API.

1. משתמש מבקר באתר שמוצגות בו מודעות.
2. קוד המפיץ מבצע את הפעולה navigator.runAdAuction(). מציין איזה שטח להצגת מודעות עומד למכירה ומי יכול להגיש הצעות מחיר. המפיצים גם צריכים לכלול סקריפט שמדרג כל הצעת מחיר, scoreAd().
3. הקוד של הקונה שהוזמן פועל כדי ליצור הצעת מחיר, כתובת URL לקריאייטיב רלוונטי של המודעה ונתונים נוספים. סקריפט הבידינג יכול לבצע שאילתה כדי לקבל נתונים בזמן אמת, כמו התקציב הנותר של קמפיין הפרסום, משירות המפתח/ערך של הקונה.
4. הקוד של בית העסק נותן ניקוד לכל הצעת מחיר ובוחר זוכה. הלוגיקה הזו משתמשת בערך הצעת המחיר, ונתונים אחרים מחזירים את הערך הרצוי של הצעת המחיר. מודעות שלא יכולות לגבור על המנצח לפי ההקשר נדחות. המוכרים יכולים להשתמש בשירות מפתחות/ערך משלו לנתונים בזמן אמת.
5. המודעה הזוכה מוחזרת כערך אטום שמוצג במסגרת מוגדרת. גם המוכר וגם בעל האתר לא יוכלו לראות את הערך הזה.
6. המכרז מדווח למוכר ולקונים שזכו.

מכרז עשוי להתרחש כשמשתמש מנווט לדף שבו מוצגת מודעה. מכרזים עשויים להיות מופעלים מראש, כדי שהקריאייטיב של המודעה יהיה מוכן כשמיקום המודעה יוצג.

המפיצים יוזמים את המכרז של המודעות, נותנים ניקוד למודעות אפשריות באמצעות לוגיקה מותאמת אישית כפונקציית scoreAd(), ואחראים לדווח על תוצאות המכרז לעצמם ולקונה הזוכה. המפיצים יכולים גם לאכוף כללים של בעלי תוכן דיגיטלי ולסנן את איכות המודעה באמצעות הפונקציה scoreAd().

המפיץ עשוי להפנות אל:

• בעלי תוכן דיגיטלי הפועלים בעצמם לאירוח תוכן מודעות באתר שלהם
• פלטפורמות בצד הספק (SSP), עבודה עם בעל האתר של הפרסום ומתן שירותים אחרים
• סקריפטים של צד שלישי, שפועלים למען בעלי תוכן דיגיטלי כדי לאפשר השתתפות במכרזי מודעות.

דרישות מוקדמות להפעלת מכרז

אתר מכירה צריך להגדיר שתי פונקציות JavaScript כדי להפעיל מכרז:

• scoreAd(), שמעניק ציונים למועמד להצגת מודעה
• reportResult(), שמטפל בדיווח על תוצאות המכרז למוכר עצמו

צריך להציג את הסקריפטים האלה דרך נקודת קצה אחת שבבעלות אתר המכירה.

scoreAd()

בית העסק צריך להגדיר פונקציית scoreAd() שמוצגת מנקודת קצה שבבעלותו. נקודת הקצה מצוינת בהגדרות המכרז בתור decisionLogicUrl. לפונקציה scoreAd() יש את החתימה הבאה:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

הפרמטרים scoreAd() הם:

• adMetaData – מטא-נתונים שרירותיים לגבי הקריאייטיב של המודעה שהקונה סיפק. זהו אובייקט JSON שניתן להפעלה בסדרה, והמוכרים והקונים יצטרכו להגדיר ולאשר את המבנה.
• bid, שהוא ערך מספרי שמייצג את הצעת המחיר.
• auctionConfig, שהיא תצורת המכרז שמשמשת לביצוע המכרז.
• trustedScoringSignals, שהם אותות שנקראים בזמן המכרז משרת המפתח/ערך של המוכר. הפלטפורמה תשתמש ב-renderUrl של מודעת ההצעה כמפתח לחיפוש הזה.
• browserSignals – אובייקט שנבנה על ידי הדפדפן, וכולל מידע שהדפדפן מכיר ואיזה סקריפט המכרז של בית העסק עשוי לרצות לאמת.
• directFromSellerSignals הוא אובייקט שעשוי להכיל את השדות הבאים: ** sellerSignals: כמו auctionConfig.sellerSignals, אבל הועבר באמצעות המנגנון directFromSellerSignals. ** auctionSignals: כמו auctionConfig.auctionSignals, אבל הועבר באמצעות המנגנון directFromSellerSignals.

הדוגמה הבאה היא של browserSignals. שימו לב ש-renderUrl של המודעה המועמדת זמין באמצעות האותות הבאים:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

בית העסק צריך להגדיר פונקציית reportResult() שנשלחת מנקודת קצה שנמצאת בבעלותו. נקודת הקצה מצוינת בהגדרת המכרז בתור decisionLogicUrl. לפונקציה reportResult() יש את החתימה הבאה:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

הפרמטרים reportResult() הם:

• auctionConfig, שהיא תצורת המכרז שמשמשת לביצוע המכרז.
• browserSignals – אובייקט שנבנה על ידי הדפדפן, וכולל מידע שהדפדפן מכיר ואיזה סקריפט המכרז של בית העסק עשוי לרצות לאמת. זהו אותו אובייקט שהועבר לפונקציה scoreAds().

הערך reportResult() מחזיר את הערך signalsForWinner, שהוא אובייקט JSON שרירותי שמועבר אל פונקציית הדיווח של הקונה הזוכה. האיסור הזה צריך לכלול כל מידע רלוונטי שהמוכר יכול לספק על המכרז שהקונה דורש כדי לדווח עליו.

הפעלת מכרז של Protected Audience API

כדי להפעיל מכירה פומבית, מפיץ חייב לבצע ארבעה שלבים עיקריים. שימו לב שהשלבים האלה יוצאים מנקודת הנחה שהמפיץ הגדיר נקודת קצה שתחזיר את קוד ה-JavaScript הנדרש שהוזכר במדריך הזה.

1. מגדירים את המכרז. השלב הזה כולל יצירת אובייקט auctionConfig. כך המוכר יכול לציין אילו קונים צריכים להשתתף במכרז, וכן לספק אותות שעשויים להיות רלוונטיים במהלך יצירת הצעת המחיר או חישוב הציון של המודעה.
2. מפעילים את המכרז על ידי קריאה ל-navigator.runAdAuction() ומעבירים את ההגדרות האישיות שיצרתם בשלב הקודם. כך נוצרת שרשרת של קונים ויוצרים הצעות מחיר. התוצאה הסופית של השלב הזה היא התאמה למודעה שניתן לעבד כדי להציג מודעה.
3. מציגים את המודעה הזוכה במסגרת מגודרת או iframe.
4. דיווח על תוצאת המכרז. הפונקציה navigator.sendReportTo() מפעילה את הדיווח. המוכר תמיד יקבל דוח של תוצאות המכרז. רק הקונה שזכה במכרז יקבל דוח. הפעולה הזו משתמשת בreportResult() של המפיץ שתואר קודם לכן במדריך הזה כדי לדווח לשרת שלו.