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

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

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

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

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

אותות דפדפן

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

{
  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`	המטבע של הצעת המחיר, שמשמש לcurrency-checking.
`render`	מילון שמתאר את הקריאייטיב שצריך להציג אם הצעת המחיר הזו זוכה במכרז. האיסור הזה כולל: `url`: כתובת ה-URL של הקריאייטיב. `width`: הרוחב של הקריאייטיב. הגודל הזה יותאם להצהרה בקבוצת תחומי העניין, ומוחלף בכל מאקרו של גודל מודעה שמופיע בכתובת ה-URL של הקריאייטיב של המודעה. כשהמודעה נטענת במסגרת מגודרת, המסגרת הפנימית של המסגרת (כלומר הגודל הגלוי לקריאייטיב של המודעה) תוקפא לגודל הזה, ולא ניתן יהיה לראות שינויים בגודל המסגרת שביצע ההטמעה. `height`: הגובה של הקריאייטיב. אפשר לעיין בהרחבה ב`width`.
`modelingSignals`	מספר שלם מסוג 0-4, 095 (12 ביט) שמועבר אל `reportWin()` עם רעש, כפי שמתואר בסכימת הרעשים והחלוקה לקטגוריות. המערכת תתעלם מערכים לא חוקיים, כמו ערכים שליליים, ערכים אינסופיים ו-`NaN`. רק 12 הביטים הנמוכים ביותר יועברו. הקונה יכול להשתמש באותות שזמינים בפונקציה `generateBid()`, כולל נתונים מנתונים של קונה מאינטראקציה ישירה (First-Party) שתועדו בזמן היצירה של קבוצת תחומי העניין ב-`userBiddingSignals`, כדי להסיק ערך שמועבר לפונקציית הדיווח על זכייה של הקונה כדי לאפשר אימון מודלים של למידת מכונה.