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

איך מזהי דיווח פועלים במכרז של 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() יהיו זמינים ל-reportWin(), הם ייבדקו כדי לוודא שהם עומדים בדרישות של k-anonymity. הבדיקה תכלול את בעלי קבוצת תחומי העניין, כתובת ה-URL של סקריפט הבידינג, כתובת ה-URL של הרנדור וגודל המודעה (גודל המודעה לא ייכלל בבדיקה הזו עד הרבעון הראשון של 2025 לפחות).buyerAndSellerReportingId

לא הוגדרו הערכים 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.