שליחת הצעת מחיר במכרז לרכישת מיקום מודעה

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

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

אתם מספקים את הלוגיקה ליצירת הצעות מחיר בפונקציית ה-JavaScript‏ generateBid() והקובץ מאוחסן בשרת שלכם. כשמוסיפים משתמש לקבוצת אינטרס, המיקום של הקובץ הזה מועבר להגדרות של קבוצת האינטרס כ-biddingLogicUrl.

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

`generateBid()`

בהמשך מפורטים הארגומנטים של הפונקציה generateBid() והמבנה של הצעת המחיר שמוחזרת מהפונקציה:


generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

ארגומנטים

‫generateBid() מקבל את הארגומנטים הבאים:

ארגומנט	תפקיד
`interestGroup`	אובייקט שמועבר על ידי הקונה של שטחי הפרסום. יכול להיות שקבוצת תחומי העניין תעודכן עם `dailyUpdateUrl`.
`auctionSignals`	מאפיין של הארגומנט auction config שמועבר אל `navigator.runAdAuction()` על ידי המוכר. המידע הזה כולל את ההקשר של הדף (למשל גודל המודעה ומזהה בעל התוכן הדיגיטלי), סוג המכרז (מחיר ראשון או מחיר שני) ומטא-נתונים אחרים.
`perBuyerSignals`	מאפיין של הארגומנט auction config שמועבר על ידי המוכר. האותות האלה יכולים לספק מידע הקשרי משרת הקונה לגבי הדף, אם המוכר הוא SSP שמבצע קריאה של בידינג בזמן אמת לשרתי הקונה ומעביר את התגובה בחזרה, או אם דף בעל התוכן הדיגיטלי יוצר קשר ישירות עם שרת הקונה. אם כן, הקונה יכול לבדוק חתימה קריפטוגרפית של האותות האלה בתוך `generateBid()` כדי להגן על עצמו מפני שינוי לא מורשה.
`trustedBiddingSignals`	אובייקט שהמפתחות שלו הם `trustedBiddingSignalsKeys` של קבוצת העניין, והערכים שלו מוחזרים בבקשה `trustedBiddingSignals`.
`browserSignals`	אובייקט שנבנה על ידי הדפדפן, שעשוי לכלול מידע על ההקשר של הדף (למשל, `hostname` של הדף הנוכחי, שאתר המכירה יכול לזייף) ונתונים על קבוצת הנושאים עצמה (למשל, רשומה של מקרים שבהם הקבוצה זכתה בעבר במכרז, כדי לאפשר הגבלת תדירות הצגת מודעות במכשיר).
`directFromSellerSignals`	אותות שמגיעים ממוכר ספציפי, בניגוד לאותות `auctionSignals` ו-`sellerSignals` שיכולים להגיע מכל משתתף שנמצא בהקשר שבו מתבצעת הפעלה של `runAdAuction`.

אותות מהדפדפן

לאובייקט browserSignals יש את המאפיינים הבאים:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}

נכס	תיאור
`topWindowHostname`	שם המארח שבו בוצעה השיחה `runAdAuction()`.
`seller`	המוֹכר שאליו נשלחת הצעת המחיר. במכרז רכיבים, הערך הזה הוא מוכר הרכיבים.
`topLevelSeller`	המוכר ברמה העליונה במכרז רכיבים, ומופיע רק במכרז רכיבים.
`requestedSize`	המאפיין `requestedSize` ממליץ על גודל מסגרת למכרז. המוכר מגדיר את הגודל המבוקש בהגדרות המכרז, והערך הופך לזמין למגישי הצעות המחיר ב-`generateBid()`. יכול להיות שהמשתתפים בהצעת המחיר יבחרו גודל תוכן שונה למודעה, והגודל שיתקבל יותאם חזותית לגודל של מאגר הרכיבים.
`joinCount`	השדה `joinCount` הוא מספר הפעמים שהמכשיר הזה הצטרף לקבוצת האינטרס הזו ב-30 הימים האחרונים, בזמן שקבוצת האינטרס נשמרה באופן רציף (כלומר, אין פערים בשמירה של קבוצת האינטרס במכשיר בגלל יציאה או תפוגה של החברות).
`recency`	השדה `recency` הוא משך הזמן (בדקות) מאז שהמכשיר הזה הצטרף לקבוצת המתעניינים הזו ועד עכשיו
`bidCount`	מספר הפעמים שקבוצת המתעניינים הזו הגישה הצעת מחיר.
`prevWinsMs`	השדה `prevWinMs` מכיל את המודעות המנצחות של קבוצת המתעניינים, ואת הזמן שחלף מאז הניצחונות הקודמים שלהן, במילישניות. שימו לב שאובייקט המודעה כאן מכיל רק את השדות `renderURL` ומטא-נתונים.
`wasmHelper`	אובייקט WebAssembly.Module שמבוסס על קבוצת האינטרסים `biddingWasmHelperURL`.
`dataVersion`	ערך Data-Version מתגובות שירות המפתח/ערך של הקונה.
`adComponentsLimit`	המספר המקסימלי של רכיבי מודעות שיוחזרו הוא `generateBid()`

חישוב הצעת מחיר

כדי לחשב ערך של הצעת מחיר, הקוד בפונקציה generateBid() יכול להשתמש במאפיינים של הפרמטרים של הפונקציה.

לדוגמה:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

החזרת הצעת מחיר

הפונקציה generateBid() מחזירה אובייקט עם המאפיינים הבאים:

נכס	תפקיד
`ad`	מטא-נתונים שרירותיים לגבי המודעה, כמו מידע שהמוכר מצפה לקבל לגבי הצעת המחיר או נכס הקריאייטיב של המודעה. המוכר משתמש במידע הזה במכרז ובלוגיקה של קבלת ההחלטות שלו.
`adCost`	ערך מספרי שמשמש להעברת עלות קליק או המרה של מפרסם לצורך דיווח, מהפונקציה generateBid לפונקציה reportWin. הדיוק של המספר הזה מוגבל למנטיסה של 8 ביט ולמעריך חזקה של 8 ביט, וכל העיגולים מתבצעים באופן סטוכסטי.
`adComponents`	רשימה אופציונלית של עד 20 רכיבים של מודעות שמורכבות מכמה חלקים, שנלקחים מהמאפיין adComponents של הארגומנט של קבוצת העניין שמועבר אל `navigator.joinAdInterestGroup()`.
`allowComponentAuction`	ערך בוליאני שמציין אם אפשר להשתמש בהצעת המחיר הזו במכרז רכיבים. אם לא מציינים ערך, ברירת המחדל היא false.
`bid`	הצעת מחיר מספרית שתשתתף במכרז. המוכר צריך להיות מסוגל להשוות בין הצעות מחיר של קונים שונים, ולכן הצעות המחיר צריכות להיות ביחידה כלשהי שהמוכר בוחר (למשל, 'דולר ארה"ב לאלף'). אם הצעת המחיר היא אפס או שלילית, קבוצת המתעניינים הזו לא תשתתף במכרז של המוכר. באמצעות המנגנון הזה, הקונה יכול להטמיע כללים של מפרסמים לגבי המיקומים שבהם המודעות שלהם יכולות להופיע או לא להופיע.
`bidCurrency`	המטבע של הצעת המחיר, שמשמש לבדיקת המטבע.
`render`	מילון שמתאר את הקריאייטיב שיוצג אם הצעת המחיר הזו תזכה במכרז. הם כוללים: ‫`url`: כתובת ה-URL של הקריאייטיב. ‫`width`: הרוחב של הקריאייטיב. הגודל הזה יושווה להצהרה בקבוצת הנושאים ויוחלף בכל פקודות מאקרו של גודל מודעה שמופיעות בכתובת ה-URL של הקריאייטיב של המודעה. כשהמודעה נטענת ב-fenced frame, הפריים הפנימי של ה-fenced frame (כלומר הגודל שגלוי לקריאייטיב של המודעה) קופא בגודל הזה, ולא ניתן לראות שינויים בגודל הפריים שבוצעו על ידי המטמיע. ‫`height`: הגובה של הקריאייטיב. מידע נוסף מפורט ב`width`.
`modelingSignals`	מספר שלם מ-0 עד 4095 (12 ביט) שמועבר אל `reportWin()`, עם הוספת רעש, כפי שמתואר בסכימת הוספת הרעש והחלוקה לדליים. המערכת תתעלם מערכים לא חוקיים, כמו ערכים שליליים, אינסופיים וערכים של `NaN`, ולא תעביר אותם. רק 12 הביטים הנמוכים ביותר יועברו. `generateBid()`הקונה יכול להשתמש באותות שזמינים בפונקציה, כולל נתונים מנתוני הקונה מאינטראקציה ישירה (First-Party) שנאספו בזמן יצירת קבוצת נושאים ב-`userBiddingSignals`, כדי להפיק ערך מסוים שמועבר לפונקציית הדיווח על הזכייה של הקונה, כדי לאפשר אימון של מודל ML.