מזהים לצורכי דיווח

איך מזהי דיווח פועלים במכרז של Protected Audience

סקירה כללית

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

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

יש שלושה מזהי דיווח משני סוגים:

• מזהי דיווח שלא ניתן לבחור
  • ‫buyerReportingId (מחרוזת)
  • ‫buyerAndSellerReportingId (מחרוזת)
• מזהי דיווח שאפשר לבחור
  • ‫selectableBuyerAndSellerReportingIds (מערך של מחרוזות)

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

מזהים לדיווח שלא ניתן לבחור

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

כשמשתמשים בפונקציית הדיווח לקונים בלי מזהי דיווח שאפשר לבחור, הפונקציה מקבלת את הערך buyerReportingId או buyerAndSellerReportingId בהתאם להתנהגות של החלפת הערך, והפונקציה של הדיווח למוכרים מקבלת את הערך buyerAndSellerReportingId. אם אף אחד מהערכים buyerReportingId או buyerAndSellerReportingId לא מוגדר בהגדרות של קבוצת המתעניינים, הפונקציה reportWin() מקבלת את שם קבוצת המתעניינים (interestGroupName) של הצעת המחיר הזוכה.

מזהים שלא ניתן לבחור לא זמינים בתוך התגים generateBid() ו-scoreAd() אם לא משתמשים בהם בשילוב עם מזהים לדיווח שאפשר לבחור.

מזהי דיווח בקבוצות בעלי עניין

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

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

דיווח של מוֹכרים

במהלך שלב הדיווח של בית העסק, הערך buyerAndSellerReportingId זמין ל-reportResult():

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

לפני שהמזהה הופך לזמין ב-reportResult(), מתבצעת בדיקה של k-anonymity עם הבעלים של קבוצת המתעניינים, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרנדור וגודל המודעה (גודל המודעה לא נכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות). אם הנתונים לא אנונימיים ברמת k, הפונקציה reportResult() עדיין תפעל, אבל ערך מזהה הדיווח לא יהיה זמין בתוך הפונקציה.

דיווח על קונים

במהלך שלב הדיווח לקונים במכרז, מזהה דיווח אחד הופך לזמין ל-reportWin(). אם מוגדר יותר ממזהה דיווח אחד בקבוצת הנושאים, יחול כלל החלפה שבו buyerAndSellerReportingId מחליף את buyerReportingId:

• אם מוגדרים גם buyerAndSellerReportingId וגם buyerReportingId, הערך של buyerAndSellerReportingId יחליף את הערך של buyerReportingId, והערך של buyerAndSellerReportingId יהיה זמין בתוך reportWin().
• אם מוגדר רק buyerReportingId, אז buyerReportingId יהיה זמין.
• אם לא מוגדרים buyerAndSellerReportingId וגם לא buyerReportingId, האפשרות interestGroupName תהיה זמינה.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

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

מוגדר רק buyerReportingId

אם רק buyerReportingId מוגדר בהגדרות של קבוצת האינטרס:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

אחרי זה, אפשר להשתמש ב-buyerReportingId בתוך reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

לפני שהתכונה תהיה זמינה ל-reportWin(), המערכת תבדוק את buyerReportingId כדי לוודא שהיא עומדת בדרישות של k-anonymity. הבדיקה תכלול את בעלי קבוצת תחומי העניין, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרכיב הגרפי וגודל המודעה (גודל המודעה לא ייכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות).

מוגדר רק buyerAndSellerReportingId

אם רק buyerAndSellerReportingId מוגדר בהגדרות של קבוצת האינטרס:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

אחרי זה, אפשר להשתמש ב-buyerAndSellerReportingId בתוך reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

לפני שהתכונה תהיה זמינה ל-reportWin(), המערכת תבדוק את buyerAndSellerReportingId כדי לוודא שהיא עומדת בדרישות של k-anonymity. הבדיקה תכלול את בעלי קבוצת תחומי העניין, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרכיב הגרפי וגודל המודעה (גודל המודעה לא ייכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות).

הוגדרו גם buyerAndSellerReportingId וגם buyerReportingId

אם גם buyerAndSellerReportingId וגם buyerReportingId מוגדרים בתצורת קבוצת האינטרס:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

אז רק buyerAndSellerReportingId יהיה זמין בתוך reportWin() בגלל התנהגות הדריסה:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

לפני שהתכונה תהיה זמינה ל-reportWin(), המערכת תבדוק את buyerAndSellerReportingId כדי לוודא שהיא עומדת בדרישות של k-anonymity. הבדיקה תכלול את בעלי קבוצת תחומי העניין, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרכיב הגרפי וגודל המודעה (גודל המודעה לא ייכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות).

לא הוגדרו הערכים buyerAndSellerReportingId ו-buyerReportingId

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

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

אז קבוצת האינטרסים name זמינה בתוך reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

לפני שהשם של קבוצת המתעניינים (interestGroupName) הופך לזמין ל-reportWin(), מתבצעת בדיקה של k-anonymity עם הבעלים של קבוצת המתעניינים, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרנדור וגודל המודעה (גודל המודעה לא נכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות).

מזהים לצורכי דיווח שאפשר לבחור

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

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

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

קבוצת אינטרס

השדה של מזהי הדיווח שאפשר לבחור – selectableBuyerAndSellerReportingIds – הוא מערך של מחרוזות שהוגדר על ידי הקונה בקבוצת המתעניינים של מודעה. אפשר גם להגדיר מזהים לצורכי דיווח שלא ניתן לבחור בהם לצד מזהים לצורכי דיווח שאפשר לבחור בהם:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

יצירת הצעות מחיר על ידי הקונה

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

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

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

הצעת מחיר עם ערך מוחזר עבור selectedbuyerAndSellerReportingId יכולה לזכות במכרז רק אם הערך של selectedbuyerAndSellerReportingId הוא k-אנונימי ביחד עם buyerAndSellerReportingId (אם יש), buyerReportingId (אם יש), הבעלים של קבוצת המתעניינים, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרכיב הגרפי וגודל המודעה (גודל המודעה לא נכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות).

ניקוד מודעות של מוכרים

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

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

דיווח של מוֹכרים

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

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

אם selectableBuyerAndSellerReportingIds הוגדר בהגדרות של קבוצת המתעניינים, והערך selectedBuyerAndSellerReportingId הוחזר מ-generateBid(), אז אי אפשר לזכות במכרז אלא אם הערכים selectedBuyerAndSellerReportingId ו-buyerAndSellerReportingId (אם יש) הם k-אנונימיים עם הבעלים של קבוצת המתעניינים, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרנדור וגודל המודעה (גודל המודעה לא נכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות), והפונקציה reportResult() לא תופעל עבור הצעת המחיר הזו. לכן, אם הפונקציה reportResult() נקראת עם ערך של selectedBuyerAndSellerReportingId, המשמעות היא שמזהי הדיווח עברו את בדיקת האנונימיות k, וכל מזהי הדיווח שהוגדרו יהיו זמינים בתוך reportResult().

דיווח על קונים

אם selectableBuyerAndSellerReportingIds הוגדר בהגדרות של קבוצת בעלי העניין, ו-selectedBuyerAndSellerReportingId הוחזר מ-generateBid(), כל מזהי הדיווח שהוגדרו בהגדרות של קבוצת בעלי העניין יהיו זמינים. חשוב לציין שכמו בדיווח על מוכרים, אם מזהי הדיווח לא אנונימיים, הם לא יוכלו לזכות במכרז והמודעה reportWin() לא תוצג עבור הצעת המחיר הזו.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

החלפת כללים

בטבלה הבאה מפורטים כללי הדריסה של מזהי דיווח שניתן לבחור ושל מזהי דיווח שלא ניתן לבחור. הדפדפן קובע את הערכים של selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId ושם קבוצת העניין שמועברים אל reportWin() לפי הלוגיקה הבאה:

• אם הצעת מחיר מחזירה את הערך selectedBuyerAndSellerReportingId, כל הערכים selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (אם הוא מוגדר בקבוצת המתעניינים) ו-buyerReportingId (אם הוא מוגדר בקבוצת המתעניינים) זמינים לדיווח.
• אחרת, אם buyerAndSellerReportingId מוגדר בקבוצת בעלי העניין, רק buyerAndSellerReportingId יהיה זמין לדיווח.
• אחרת, אם buyerReportingId מוגדר בקבוצת בעלי העניין, רק buyerReportingId יהיה זמין לדיווח.
• אחרת, רק קבוצת בעלי העניין name זמינה לדיווח.

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

אינטראקציה ושיתוף משוב

• מידע נוסף על מזהי דיווח זמין בקטע בנושא מזהי דיווח במאמר Protected Audience (קהל מוגן) – הסבר.
• ‫GitHub: אפשר להעלות שאלות ולעקוב אחרי דיונים בבעיות במאגר ה-API.
• ‫W3C: אפשר לדון בתרחישים לדוגמה בתחום בשיחה של WICG.
• הודעות: הצטרפות לרשימת התפוצה או הצגתה.
• תמיכה למפתחים בנושא ארגז החול לפרטיות: אפשר לשאול שאלות ולהצטרף לדיונים במאגר התמיכה למפתחים בנושא ארגז החול לפרטיות.
• ‫Chromium: שליחת באג ב-Chromium כדי לשאול שאלות על ההטמעה שזמינה לבדיקה ב-Chrome.