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

מידע נוסף על הגדרת מכרז של 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 מלונות

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

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

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

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

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

נכס דוגמה תפקיד
trustedScoringSignalsUrl https://seller.example/scoring-signals כתובת ה-URL של שרת המפתח/ערך של המוכר. המערכת תשלח שאילתה לפרמטר הזה במהלך חישוב הציון של המודעה, תוך שימוש בכתובת ה-URL לעיבוד של הקריאייטיב בתור המפתח. המקור של השדה הזה צריך להיות זהה לזה של שדה אתר המכירה.
auctionSignals {"category":"news"} אובייקט בפורמט 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 אטומה מסוג urn:uuid אם הערך הוא 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, שמציין שלא נבחרו מודעות. במקרה כזה, המוכר עשוי לבחור לעבד מודעה שממוקדת לפי הקשר.