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

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

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

סקירה כללית

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

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

מזהי הדיווח יהיו זמינים לפונקציות של מוכרים וקונים של Protected Audience — זמינות של מזהי דיווח

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

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

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

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

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

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

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

  // ...
}

שינוי כללים

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

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

בטבלה הבאה מתוארת התנהגות ההחלפה:

האם מזהי הדיווח מוגדרים בהגדרות של קבוצת העניין?			מזהים של דיווח שזמינים
`selectableBuyerAnd SellerReportingIds`	`buyerAndSeller ReportingId`	`buyerReportingId`	`reportWin()`	`reportResult()`
כן, ובחרת באפשרות ב-`generateBid()`	אופציונלי	אופציונלי	1) `selectedBuyerAnd SellerReportingIds` 2) `buyerAndSeller ReportingId` (אם הוגדר) 3) `buyerReportingId` (אם הוגדר)	1) `selectedBuyerAnd SellerReportingIds` 2) `buyerAndSeller ReportingId` (אם מוגדר)
לא, או לא נבחרה ב-`generateBid()`	כן	Ignored (דפים שהמערכת מתעלמת מהם)	`buyerAndSeller ReportingId`	`buyerAndSeller ReportingId`
לא, או לא נבחרה ב-`generateBid()`	לא	כן	`buyerReportingId`	ללא
לא, או לא נבחרה ב-`generateBid()`	לא	לא	`interestGroupName`	ללא

יצירת מעורבות ושיתוף משוב

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

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

סקירה כללית

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

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

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

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

רק buyerReportingId מוגדר

רק buyerAndSellerReportingId מוגדר

גם buyerAndSellerReportingId וגם buyerReportingId מוגדרים

לא מוגדר אף אחד מהמשתנים buyerAndSellerReportingId או buyerReportingId

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

קבוצת עניין

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

דירוג מודעות של מוכרים

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

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

שינוי כללים

יצירת מעורבות ושיתוף משוב

רק `buyerReportingId` מוגדר

גם `buyerAndSellerReportingId` וגם `buyerReportingId` מוגדרים

לא מוגדר אף אחד מהמשתנים `buyerAndSellerReportingId` או `buyerReportingId`