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

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

סקירה כללית

מזהי דיווח הם מזהים שמשויכים למודעה וזמינים לשימוש ביצירת הצעת מחיר, בשקלול הצעת מחיר ובדיווח. מזהי הדיווח מסופקים על ידי הקונה בהגדרות של קבוצת האינטרסים, והם הופכים לזמינים ב-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 עם הבעלים של קבוצת העניין, כתובת ה-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 (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 (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 (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;
}

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

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

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

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