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

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

מכרזים במכשיר שמורצים על ידי מוכרים

מכרז בשילוב עם Protected Audience API במכשיר מופעל באתר שמוכר שטחי פרסום, והגורם שמפעיל את המכרז נקרא מוכר. יכולים להיות הרבה גורמים שפועלים כמוכרים: אתר יכול להפעיל מכרז משלו למודעות, או לכלול סקריפט של צד שלישי כדי להפעיל את המכרז בשבילו, או להשתמש בפלטפורמת 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 של קובץ JavaScript של worklet עם לוגיקת החלטה לגבי מכרז. השדה הזה צריך להיות מאותו מקור כמו השדה seller [אתר המכירה].
interestGroupBuyers [https://buyer-1.example,
https://buyer-2.example,
...]		 מקורות של כל הבעלים של קבוצות בעלי העניין שהתבקשו להגיש הצעות מחיר במכרז

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

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

נכס דוגמה תפקיד
trustedScoringSignalsUrl https://seller.example/scoring-signals כתובת ה-URL של שרת צמדי מפתח/ערך של המוכר. השאילתה הזו תופעל במהלך תהליך הניקוד של המודעה, באמצעות כתובת ה-URL של נכס הקריאייטיב כערך המפתח. השדה הזה צריך להיות מאותו מקור כמו השדה seller [אתר המכירה].
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 true|false ערך בוליאני שמורה להבטיח שהערך שמוחזר מהפונקציה runAdAuction() יהיה FencedFrameConfig אם הערך הוא true (לשימוש ב-<fencedframe>), או כתובת URL אטומה מסוג urn:uuid אם הערך הוא false (לשימוש ב-<iframe>). ברירת המחדל היא false.

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

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

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

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

הפעלת המכרז

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

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

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