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

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

סקירה כללית

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

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

• joinAdInterestGroup() tasks
  • הגדרת דגלים של בקשות לשרת
  • הגדרת מזהים של הצגת מודעות
  • הגדרת העדיפות של קבוצות נושאי עניין
  • הגדרת אותות בידינג מהימנים
• generateBid() tasks
  • קריאת אותות מהדפדפן
  • כתובת URL להחזרת רכיב ה-Render
  • מזהה הדיווח שמוחזר

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

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

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 לבין ההגדרות של קבוצות נושאים במכשיר הם:

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

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

joinAdInterestGroup() משימות

צריך לבצע את המשימות הבאות עבור השיחה joinAdInterestGroup().

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

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

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

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

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

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

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

כדי לטפל במידע החסר על המודעה, הקונה שומר מזהה (adRenderId ו-adComponentRenderId) שמשויך לכל מודעה בהגדרות של קבוצת נושאי העניין. המזהה צריך להיות מחרוזת DOM באורך של 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 נוצר עבור המוכר. כדי לבחור קבוצות של נושאים שמעניינים קונים שונים, הדפדפן מחליט על סמך הגודל של מטען הייעודי (payload) שעבר סריאליזציה. כברירת מחדל, כל קונה מקבל גודל שווה. חשוב לדעת שהתעדוף בפועל מתבצע בשרתי B&A, ולא בזמן יצירת מטען הייעודי (payload) של הבקשה.

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

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

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

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

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

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

הנתונים הבאים שהושמטו יכולים להימסר על ידי שירות K/V:

• ‫userBiddingSignals אם נעשה בו שימוש על ידי הקונה
• metadata שמשויכים לכל מודעה
• adRenderId שמשויכים לכל מודעה
• מזהה דיווח

אחת הגישות האפשריות היא לכלול מזהה ייחודי במפתחות של אותות הבידינג המהימנים, ואז לשלוח את הנתונים המשויכים לשרת כדי שיהיה אפשר לטעון אותם לשירות Key/Value. עם זאת, ההטמעה בפועל תלויה בטכנולוגיית הפרסום, וה-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'
          }   
        },
      ]
    }
  })
});

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

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

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

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

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

generateBid() משימות

צריך לבצע את המשימות הבאות עבור השיחה generateBid().

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

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

{
  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:

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

מכיוון שהאובייקט ads מושמט ממטען הייעודי (payload) של מכרז 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
  ]
})

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

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.

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

השלבים הבאים

אלה המשאבים שעומדים לרשותכם

מידע נוסף

• מידע נוסף על הגדרות המכרז של B&A ב-Chrome
• כדי להתנסות ב-Protected Audience באמצעות B&A, אפשר לפעול לפי ההוראות ב-codelab בנושא בדיקות מקומיות מקצה לקצה.

יש לך שאלות?

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