שילוב עם B&A כקונים

שירותי בידינג ומכרזים (B&A) הם קבוצה של שירותים לקונים ולבעלי תוכן דיגיטלי שמפעילים בסביבת מחשוב אמינה (TEE) כדי להקל על מכרז של קהל מוגן (PA). במדריך למפתחים הזה מוסבר איך קונים יכולים לשלב מכרז B&A PA ב-Chrome.

סקירה כללית

כדי להשתתף במכרז של קהל מוגן באמצעות שירותי B&A, הקונה מעדכן את קבוצת האינטרסים (IG) כדי לבצע אופטימיזציה של עומס העבודה (payload) ולשפר את זמן האחזור במכרז.

הקונה נדרש לבצע את משימות האופטימיזציה הבאות של עומס העבודה:

קבוצת אינטרס בנושא B&A

בהמשך מופיעה דוגמה להגדרה של קבוצת תחומי עניין במכרז B&A PA עם אופטימיזציה של מטען נתונים:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

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

שדות B&A IG אפליקציית IG במכשיר כלול במטען הייעודי של מכרז B&A
auctionServerRequestFlags משומש לא בשימוש לא
userBiddingSignals לא מומלץ: משומש לא, אם הדגל omit-user-bidding-signals מוגדר
adRenderId ב-ads וב-adComponents משומש לא בשימוש אם הדגל omit-ads מוגדר, השדה adRenderId ב-ads זמין רק ב-browserSignals.prevWins של עומס העבודה. adRenderId שהוגדר ב-adComponents לא נכלל במטען הייעודי.

אם הדגל omit-ads לא מוגדר, האפשרות זמינה ב-browserSignals.prevWins, ב-interestGroup.adRenderIds וב-interestGroup.adComponentRenderIds.
renderURL ב-ads וב-adComponents משומש משומש לא
metadata ב-ads וב-adComponents לא בשימוש משומש לא
מזהי דיווח ב-ads משומש משומש לא
  • השדה auctionServerRequestFlags מאפשר להגדיר דגלים שמורים לדפדפן להשמיט נתונים מסוימים ממטען הייעודי של מכרז B&A.
  • אפשר להגדיר את הערך userBiddingSignals בקבוצת האינטרסים, אבל מומלץ להשמיט אותו באמצעות הדגל omit-user-bidding-signals. אפשר לספק את האותות שהושמט באמצעות שירות K/V.
  • השדה adRenderId מוגדר יחד עם השדה renderURL המשויך, אבל רק השדה adRenderId יהפוך לחלק ממטען הנתונים של המכרז של B&A. כתובת ה-URL לעיבוד החזותי שתוחזר מ-generateBid() בשלב מאוחר יותר במהלך המכרז חייבת להתאים לכתובת ה-URL לעיבוד החזותי שהוגדרה ב-IG.
  • מזהי הדיווח מוגדרים ב-IG של B&A, אבל הם לא כלולים בעומס הנתונים של המכרז ב-B&A. מזהה הדיווח שמוחזר מ-generateBid() מאוחר יותר במהלך המכרז חייב להתאים לכתובת ה-URL לעיבוד הגרפי שמוגדרת ב-IG.
  • מזהי ad.metadata ודיווח לא נכללים במטען הייעודי של מכרז B&A, ובמקום זאת הנתונים האלה הופכים לזמינים באמצעות השימוש בשירות המפתח/הערך המהימן.

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

joinAdInterestGroup() משימות

צריך לבצע את הפעולות הבאות בקריאה ל-joinAdInterestGroup().

הגדרת דגלים לבקשות מהשרת

השדה auctionServerRequestFlags של קובץ התצורה joinAdInterestGroup() מקבל את הדגלים הבאים:

דגל תיאור
omit-user-bidding-signals הדגל omit-user-bidding-signals משמיט את האובייקט userBiddingSignals במטען הייעודי של המכרז.

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

הערך של adRenderId יהיה זמין במאפיין prevWins של browserSignals.

אם הדגל לא מוגדר, השדות adRenderIds ו-adComponentRenderIds בארגומנט interestGroup של generateBid() יכללו את מזהי הרינדור התואמים של המודעות.

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

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

דוגמה לשימוש:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

הגדרת מזהי רינדור של מודעות

כדי לצמצם את גודל המטען הייעודי (payload) של מכרז B&A, אובייקטים ads ו-adComponents של קבוצת האינטרסים לא נכללים, וכתוצאה מכך, האובייקטים האלה לא זמינים בתוך הפונקציה generateBid() שפועלת ב-Bidding Service.

כדי לטפל במידע החסר על המודעות, הקונה שומר מזהה (adRenderId ו-adComponentRenderId) שמשויך לכל מודעה בהגדרה של קבוצת תחומי העניין. המזהה חייב להיות DOMString באורך 12 בייטים או פחות. אם המזהה מקודד ב-Base64, האורך שלו חייב להיות 12 בייטים או פחות.

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

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

ה-adRenderId שמשויך למודעות יהיה זמין ב-prevWins.browserSignals ב-generateBid().

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

הגדרת העדיפויות של קבוצות תחומי עניין

ב-Chrome, הקונים יכולים לתעדף קבוצות של תחומי עניין. אם מגיעים למגבלת הגודל של המטען הייעודי לכל קונה שהוגדרה על ידי המוכר, המערכת משתמשת בערכי העדיפות של קבוצות העניין כדי להסיר קבוצות עניין עם עדיפות נמוכה יותר לקונה יחיד כשיוצרים את המטען הייעודי של מכרז B&A עבור המוכר. כדי לבחור בין קבוצות של תחומי עניין של קונים שונים, הדפדפן מחליט על סמך גודל המטען השימושי בסדרת בייטים. כברירת מחדל, לכל קונה מוקצה גודל שווה. חשוב לדעת שהעדיפות בפועל מתבצעת בשרתים של B&A, ולא בזמן יצירת עומס העבודה של הבקשה.

העדיפות מחושבת בזמן המכרז באמצעות וקטורי העדיפות של הקונה (priorityVector) ואותות העדיפות של המוכר (prioritySignals). לקונה יש אפשרות לשנות את אות העדיפות של המוכר.

נכס תיאור
וקטור העדיפות הקונה מספק את הווקטורים כערך של המפתח priorityVector משירות ה-K/V
אותות בעדיפות גבוהה המוכר מספק את האותות על ידי הגדרת priority_signals של הגדרת המכרז
שינוי של אותות העדיפות הקונה מספק את ההחרגה בשדה priority_signals_overrides של PerBuyerConfig בתצורת המכרז.

במהלך המכרז, הדפדפן מחשב את המכפלה הסקלרית הדלה של המפתחות התואמים ב-priorityVector וב-prioritySignals כדי לקבוע את העדיפות. בתרשים הבא, העדיפות מחושבת לפי (4 * 2) + (3 * -1) שמופחת ל-8 + -3, כך שעדיפות קבוצת האינטרסים הזו בזמן המכרז היא 5.

כל מפתח בוקטור העדיפות ובאובייקטים של אותות העדיפות מוכפל זה בזה, ואז התוצאות מתווספות זו לזו כדי לחשב את העדיפות
איור 1: חישוב תעדוף באמצעות הווקטורים של הקונה והאותות של המוכר

יש גם אותות נוספים שאפשר להשתמש בהם כדי לתעדף את הבדיקות והשיפורים:

Signal תיאור
deviceSignals.one הערך הוא תמיד 1, והוא שימושי להוספת קבוע למכפלת הבינארית.
deviceSignals.ageInMinutes הערך מתאר את גיל קבוצת העניין (הזמן שחלף מאז ההצטרפות האחרונה לקבוצת העניין) בדקות כמספר שלם בין 0 ל-43,200.
deviceSignals.ageInMinutesMax60 הערך מתאר את אותו הדבר כמו האות ageInMinutes, אבל הערך המקסימלי הוא 60. אם הקבוצה נוצרה לפני יותר משעה, הפונקציה מחזירה את הערך 60.
deviceSignals.ageInHoursMax24 הערך מתאר את הגיל של קבוצת העניין בשעות, עד 24 שעות. אם הקבוצה נוצרה לפני יותר מיום, הפונקציה מחזירה את הערך 24.
deviceSignals.ageInDaysMax30 הערך מתאר את הגיל של קבוצת העניין בימים, עד 30 ימים. אם הקבוצה נוצרה לפני יותר מ-30 יום, המערכת תחזיר את הערך 30.

מידע נוסף זמין במאמר ההסבר ב-GitHub.

הגדרת אותות בידינג מהימנים

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

שירות K/V יכול לספק את הנתונים הבאים שהוחמצו:

  • userBiddingSignals אם הרוכש משתמש בה
  • metadata שמשויך לכל מודעה
  • adRenderId שמשויך לכל מודעה
  • מזהה דיווח
הנתונים שהוחמצו מקבוצת העניין יכולים להישלח לשרת האיסוף של הקונה. שרת האיסוף דוחף את הנתונים לשירות המפתח/הערך, ובשלב מאוחר יותר הדפדפן טוען את הנתונים האלה משירות המפתח/הערך.
איור 2: דוגמה להגדרה של אותות מהימנים

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

בדוגמה הבאה מתוארת גישה אחת שאפשר ליישם:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

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

אם צריך, החזרת אות עדכון של קבוצת תחומי עניין מ-K/V

המפתח updateIfOlderThanMs של האותות המהימנים משמש לעדכון של קבוצת העניין מוקדם יותר מהמרווח היומי הרגיל. אם לא הצטרפו משתמשים לקבוצת העניין או שהיא לא עודכנה במשך פרק זמן שחורג מערך המילי-שניות שהוחזר למפתח updateIfOlderThanMs, קבוצת העניין תתעדכן באמצעות מנגנון updateURL. חשוב לדעת ש-Chrome לא יעדכן את קבוצות תחומי העניין בתדירות גבוהה יותר מפעם אחת בכל 10 דקות.

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

מידע נוסף זמין במאמר הזה.

generateBid() משימות

צריך לבצע את הפעולות הבאות בקריאה ל-generateBid().

קריאת אותות מהדפדפן

אובייקט browserSignals שמוענק לקריאה generateBid() של B&A נראה כך:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

המאפיינים החדשים או המשוכתבים הבאים זמינים ב-browserSignals:

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

הוא שונה כך שיציג את האובייקט adRenderId במקום את האובייקט ad.
wasmHelper אובייקט הידור של הקוד שסופק מ-biddingWasmHelperURL.
dataVersion שרת מהימן יכול לכלול כותרת תגובה מספרית מסוג Data-Version, שתהיה זמינה ב-generateBid().

מידע נוסף זמין במאמר ההסבר ב-GitHub.

החזרת כתובת URL לעיבוד מ-generateBid()

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

אחת מהגישות האפשריות היא לשמור על כתובת URL בסיסית, ולאכלס את התבנית במידע מ-interestGroup ומ-trustedBiddingSignals.

בדוגמה הזו, אנחנו מגדירים 4 מודעות על סמך הצבע והמוצר:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

לאחר מכן שולחים את הצבע המועדף על המשתמש ואת פרטי המוצר כדי שייטמעו בשירות המפתח/הערך:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

בשלב מאוחר יותר, כשהמכרז יתבצע, אותות הבידינג המהימנים יהיו זמינים ב-generateBid(), וניתן יהיה להשתמש במידע הזה כדי לשחזר את כתובת ה-URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

החזרת מזהי דיווח מ-generateBid()

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

בדוגמה הזו, נבחרה מודעה 1 ומזהה הרינדור המשויך לה מוחזר מ-generateBid():

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

המזהה לצורכי דיווח שהוחזר יהיה זמין ב-reportWin() עד buyerReportingSignals:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

אם הערך buyerReportingId לא מוחזר מ-generateBid(), הערך interestGroupName יהיה זמין ב-buyerReportingSignals במקום ב-buyerReportingId.

מידע נוסף זמין במדריך בנושא מזהה דיווח.

השלבים הבאים

המשאבים הבאים זמינים לכם

מידע נוסף

יש לך שאלות?