דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

במהלך המכרז, הדפדפן מאחזר את הלוגיקה של הבידינג שצוינה בשדה biddingLogicUrl ומבצע את הפונקציה generateBid() עבור כל קבוצת תחומי עניין בסביבה מבודדת מאובטחת שמוגבלת בתקשורת שלה עם הקשר חיצוני. כשמריצים את הפקודה generateBid(), הדפדפן מעביר אותות לפונקציה כארגומנטים. האותות האלה מכילים מידע שונה ממקורות שונים, כמו נתונים מאינטראקציה ישירה (First-Party), נתונים של בעל התוכן הדיגיטלי, נתונים בזמן אמת ועוד. אפשר להשתמש באותות האלה כדי לחשב את הצעת המחיר, והערך יוחזר מהקריאה לפונקציה 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
}

מאפיין (property)	תיאור
`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() מחזיר אובייקט עם המאפיינים הבאים:

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