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

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