להגדיר מכירה פומבית של מודעות בדף של בעל האתר

איך מגדירים מכרז של Protected Audience API

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

מכרז של Protected Audience במכשיר פועל באתר שמוכר שטחים להצגת מודעות, ואנחנו מתייחסים לגורם שמפעיל את המכרז בתור המפיץ. גורמים רבים עשויים לפעול כספקים: אתר יכול להפעיל מכרז מודעות משלו, לכלול סקריפט של צד שלישי כדי להריץ עבורו את המכרז, או להשתמש ב-SSP שמשלב הפעלת מכרז במכשיר עם פעילויות אחרות של מכרז מודעות בצד השרת. למפיצים יש שלוש עבודות בסיסיות במכרז של מודעות במכשיר:

1. המפיצים מחליטים (א) אילו קונים יוכלו להשתתף, ו-(ב) אילו הצעות מחיר מקבוצות האינטרס של הקונים האלו כשירות להיכנס למכרז. כך המפיץ יכול לאכוף את הכללים של האתר לגבי המודעות שמותר להציג בדף.
2. המפיצים אחראים ללוגיקה העסקית של המכירה הפומבית: קוד JavaScript, שלוקח בחשבון את המחיר והמטא-נתונים של כל הצעת מחיר, ומחשב ציון מסוג 'רצוי'. הצעת המחיר עם ציון הרלוונטיות הגבוה ביותר זוכה במכרז.
3. המפיצים מספקים דיווח על תוצאת המכרז, כולל מידע על מחיר הסילוק וכל תשלום אחר. גם הקונים הזוכים ומפסידים יכולים לדווח בעצמם.

במסמך הזה נסביר איך להגדיר מכרז במכשיר ולהתחיל אותו.

הגדרת מכרז של מודעות Protected Audience API

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

const auctionConfig = {
  seller: 'https://seller.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://buyer-1.example': {...},
    'https://buyer-2.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://buyer-1.example': 50,
    'https://buyer-2.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://component-seller.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ],
  resolveToConfig: [true|false],
};

AuctionConfig מלונות

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

מאפיינים נדרשים

המאפיינים הנדרשים היחידים ל-auctionConfigs הם seller, decisionLogicUrl ו-interestGroupBuyers.

מאפיין (property)	דוגמה	תפקיד
אתר מכירה	https://seller.example	מקור המפיץ.
decisionLogicUrl	https://seller.example/decision-logic.js	כתובת URL ל-worklet לוגי להחלטת JavaScript במכרז. המקור של השדה הזה צריך להיות זהה למקור של השדה של בית העסק.
interestGroupBuyers	[https://buyer-1.example, https://buyer-2.example, ...]	המקורות של כל הבעלים של קבוצות האינטרס שביקשו להגיש הצעות מחיר במכרז

מאפיינים אופציונליים

שאר המאפיינים של auctionConfigs הם אופציונליים.

מאפיין (property)	דוגמה	תפקיד
trustedScoringSignalsUrl	https://seller.example/scoring-signals	כתובת ה-URL של שרת Key/Value של בית העסק. המערכת תשלח שאילתה בתהליך חישוב הציון של המודעה, כאשר כתובת ה-URL לעיבוד של הקריאייטיב היא המפתח. המקור של השדה הזה צריך להיות זהה למקור של השדה של בית העסק.
auctionSignals	{"category":"חדשות"}	אובייקט JSON שניתן בסדרה, ומייצג את האותות שזמינים לכל הקונים והמוכרים שמשתתפים במכרז.
sellerSignals	{...}	אובייקט JSON שניתן בסדרה, ומייצג אותות שזמינים רק למוכרים.
perBuyerSignals	{https://dsp.example: {...}, https://another-buyer.example: {...}, ... }	אותות שזמינים לקונה ספציפי. האותות יכולים להגיע מאתרי המכירה וגם מהקונים עצמם.
perBuyerTimeouts	{https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...},	זמן ריצה מקסימלי באלפיות השנייה של סקריפט generateBid() של קונה מסוים. סמל תו כללי יחול על כל קונה שלא הוגדר עבורו זמן קצוב לתפוגה.
sellerTimeout	100	זמן ריצה מקסימלי באלפיות השנייה של סקריפט ScoreAd() של מפיץ.
componentAuctions	[{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...]	הגדרות נוספות למכרזים של רכיבים.
resolveToConfig	נכון|לא נכון	הוראה בוליאנית שמוחזרת מ-runAdAuction() כדי לפענח ל-FencedFrameConfig אם הערך הוא true (לשימוש ב-<fencedframe>), או לכתובת URL אטומה:uuid if false (לשימוש ב-<iframe>). ברירת המחדל היא false.

העברת אותות באופן אסינכרוני

אפשר לציין את הערכים של חלק מהאותות (אלה שהוגדרו על ידי השדות auctionSignals, sellerSignals, perBuyerSignals ו-perBuyerTimeouts) כערכים מוחשיים, אלא כהבטחות. כך מותר לחלקים מהמכרז, כמו טעינת סקריפטים ואותות מהימנים והשקה של תהליכי worklet מבודדים, לחפוף לחישוב (או לאחזור הרשת) של הערכים האלה. הסקריפטים של worklet יראו רק את הערכים שתוזמנו. אם הבטחה כזו תידחה, המכרז יבוטל אלא אם היא תיכשל כבר או תבוטל בדרכים אחרות.

הגדרת מכרז עם כמה אתרי מכירה

במקרים מסוימים, ייתכן שכמה אתרי מכירה ירצו להשתתף במכרז, והזוכים במכרזים השונים יועברו למכרז אחר, שיופעל על ידי מוכר אחר. המכרזים הנפרדים האלה שמועברים נקראים 'מכרזים רכיבים'. כדי לאפשר את המכרזים של הרכיבים האלה, האובייקט componentAuctions יכול להכיל הגדרות של מכרזים נוספים עבור כל מכירה פומבית של רכיבים באתר מכירה. הצעת המחיר הזוכה בכל אחד מהמכרזים שנכללים במכרז תועבר למכרז "ברמה העליונה", שבו תיקבע אפשרות זו הסופית. ייתכן של-auctionConfig במכרזים של רכיבים אין componentAuctions משלהם. כשהערך בשדה componentAuctions לא ריק, הערך של interestGroupBuyers חייב להיות ריק. כלומר, בכל מכרז של קהל מוגן, יש מוכר יחיד ולא מכרז רכיבים, או שכל הצעות המחיר מגיעות ממכרזים רכיבים, והמכרז ברמה העליונה יכול לבחור רק מבין הזוכים במכרזים שנכללים.

הפעלת המכרז

המפיץ מגיש בקשה לדפדפן של המשתמש להתחיל מכרז של מודעות על ידי קריאה ל-navigator.runAdAuction().

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

הקריאה runAdAuction() מחזירה הבטחה שמובילה למודעה. לא ניתן לקוד בדף של בעל התוכן הדיגיטלי לבדוק את המודעה הזוכה או ללמוד על התוכן שלו מהתוצאה של runAdAuction(). אם הדגל resolveToConfig הוגדר כ-True ב-AuctionConfig, מוחזר אובייקט FencedFrameConfig שאפשר לעבד רק במסגרת מגודרת. אם הדגל הוגדר כ-False, מוחזר URN אטום שאפשר לעבד ב-iframe. ייתכן שהפונקציה runAdAuction מחזירה ערך null, מה שמצביע על כך שלא נבחרה מודעה. במקרה כזה, המפיץ עשוי לבחור להציג מודעה שממוקדת לפי הקשר.