סקירה כללית על Private Aggregation API

יצירת דוחות של נתונים מצטברים על סמך נתונים מ-Protected Audience ונתונים מאתרים שונים מ-Shared Storage.

כדי לספק תכונות קריטיות שהאינטרנט מסתמך עליהן, Private Aggregation API נוצר כדי לצבור נתונים מאתרים שונים ולדווח עליהם באופן שמגן על הפרטיות.

סטטוס ההטמעה

מהו Private Aggregation API

Private Aggregation API מאפשר למפתחים ליצור דוחות של נתונים נצברים עם נתונים מ-Protected Audience API ונתונים מאתרים שונים מ-Shared Storage.

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

לדוגמה, אם תועדו בעבר נתונים דמוגרפיים ונתונים גיאוגרפיים ב-Shared Storage, תוכלו להשתמש ב-Private Aggregation API כדי ליצור תרשים היסטוגרמה שיציג לכם בערך כמה משתמשים בניו יורק צפו בתוכן שלכם באתרים שונים. כדי לצבור את המדידה הזו, אפשר לקודד את המאפיין 'מיקום גיאוגרפי' במפתח הצבירה ולספור את המשתמשים בערך שאפשר לצבור.

מושגים מרכזיים

כששולחים קריאה ל-Private Aggregation API עם מפתח צבירת נתונים וערך שניתן לצבור, הדפדפן יוצר דוח שניתן לצבור.

דוחות שאפשר לצבור נשלחים לשרת שלכם לאיסוף ולצבירה. הדוחות שנאספים בחבילה עוברים עיבוד מאוחר יותר על ידי Aggregation Service, ונוצר דוח סיכום.

במאמר יסודות של Private Aggregation API מוסבר בהרחבה על המושגים המרכזיים שקשורים ל-Private Aggregation API.

הבדלים ביחס לדיווח על שיוך

ל-Private Aggregation API יש הרבה מאפיינים משותפים עם Attribution Reporting API. Attribution Reporting API הוא ממשק API עצמאי שנועד למדוד המרות, ואילו Private Aggregation נועד למדידות בכמה אתרים בשילוב עם ממשקי API כמו Protected Audience API ו-Shared Storage. שני ממשקי ה-API יוצרים דוחות שאפשר לצבור, שמשמשים את הקצה העורפי של Aggregation Service ליצירת דוחות סיכום.

דיווח על שיוך (Attribution) משייך נתונים שנאספו מאירוע חשיפת מודעה ומאירוע המרה, שמתרחשים בזמנים שונים. Private Aggregation API מודד אירוע יחיד באתרים שונים.

בדיקת ה-API

כדי לבדוק את Private Aggregation API באופן מקומי, מפעילים את כל ממשקי ה-API של פרטיות בפרסום בקטע chrome://settings/adPrivacy.

מידע נוסף על בדיקות זמין במאמר ניסוי והשתתפות.

שימוש בהדגמה

הדמו של Private Aggregation API לאחסון שיתופי זמין בכתובת goo.gle/shared-storage-demo, והקוד זמין ב-GitHub. הדמו מטמיע את הפעולות בצד הלקוח ויוצר דוח שניתן לצבור ולהעביר לשרת.

בעתיד יפורסם הדגמה של Private Aggregation API ל-Protected Audience API.

תרחישים לדוגמה

Private Aggregation API הוא ממשק API לשימוש כללי למדידת ביצועים בכמה אתרים. אפשר להשתמש בו ב-worklets של Shared Storage ושל Protected Audience API. השלב הראשון הוא להחליט מהו המידע הספציפי שרוצים לאסוף. נקודות הנתונים האלה הן הבסיס למפתחות הצבירה.

עם נפח אחסון משותף

Shared Storage מאפשר לקרוא ולכתוב נתונים בכמה אתרים בסביבה מאובטחת כדי למנוע דליפות, ו-Private Aggregation API מאפשר למדוד נתונים בכמה אתרים שמאוחסנים ב-Shared Storage.

מדידת היקף החשיפה למשתמשים ייחודיים

יכול להיות שתרצו למדוד כמה משתמשים ייחודיים צפו בתוכן שלהם. Private Aggregation API יכול לספק תשובה כמו "כ-317 משתמשים ייחודיים צפו ב-Content ID‏ 861".

אפשר להגדיר דגל ב-Shared Storage כדי לציין אם המשתמש כבר צפה בתוכן או לא. בביקור הראשון שבו הדגל לא קיים, מתבצעת קריאה ל-Private Aggregation ואז הדגל מוגדר. בביקור הבא של המשתמש, כולל באתרים אחרים, תוכלו לבדוק את Shared Storage ולדלג על שליחת דוח ל-Private Aggregation אם הדגל מוגדר. מידע נוסף על שיטות להטמעה של מדידת הנתונים האלה זמין בסקירה המפורטת בנושא היקף החשיפה.

מדידת נתונים דמוגרפיים

יכול להיות שתרצו למדוד את המאפיינים הדמוגרפיים של המשתמשים שראו את התוכן שלכם באתרים שונים.

באמצעות צבירת נתונים פרטית אפשר לקבל תשובה, למשל "כ-317 משתמשים ייחודיים הם בגילאי 18 עד 45 ומגרמניה". שימוש ב-Shared Storage כדי לגשת לנתונים דמוגרפיים מהקשר של צד שלישי. בשלב מאוחר יותר, תוכלו ליצור דוח עם Private Aggregation על ידי קידוד המאפיינים 'קבוצת גיל' ו'מדינה' במפתח הצבירה.

מדידת תדירות של אלף ומעלה

יכול להיות שתרצו למדוד את מספר המשתמשים שראו קטע תוכן או מודעה לפחות K פעמים בדפדפן נתון, עבור ערך K שנבחר מראש.

באמצעות צבירת נתונים פרטית אפשר לקבל תשובה כמו "כ-89 משתמשים צפו ב-Content ID‏ 581 לפחות 3 פעמים". אפשר להגדיל את המונה באחסון המשותף מאתרים שונים, ואפשר לקרוא אותו בתוך ווירטואל וויט. כשמספר האירועים מגיע ל-K, אפשר לשלוח דוח באמצעות Private Aggregation.

שיוך לכמה נקודות מגע

שיוך שיווק הוא שיטה שמפרסמים משתמשים בה כדי לקבוע את התרומה של שיטות השיווק והאינטראקציות הבאות עם המודעות למכירות או להמרות.

באמצעות Protected Audience API

Protected Audience API מאפשר ליישם תרחישים לדוגמה של טירגוט מחדש ושל קהלים בהתאמה אישית, ו-Private Aggregation מאפשר לדווח על אירועים מ-worklets של קונים ומוכרים. אפשר להשתמש ב-API למשימות כמו מדידת ההתפלגות של הצעות המחיר במכרזים.

מ-worklet של Protected Audience API, אפשר לצבור את הנתונים ישירות באמצעות contributeToHistogram() ולדווח על הנתונים על סמך טריגר באמצעות contributeToHistogramOnEvent(), שהוא תוסף מיוחד ל-Protected Audience API.

הפונקציות הזמינות

הפונקציות הבאות זמינות באובייקט privateAggregation שזמין ב-worklets של Shared Storage ו-Protected Audience API.

contributeToHistogram()

אפשר להפעיל את privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), כאשר מפתח הצבירה הוא bucket והערך שניתן לצבור הוא value. לפרמטר bucket נדרש BigInt. צריך להזין מספר שלם לפרמטר value.

דוגמה לאופן שבו אפשר להפעיל אותו באחסון משותף למדידת פוטנציאל החשיפה:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

דוגמת הקוד הקודמת תבצע קריאה ל-Private Aggregation בכל פעם שתוכן iframe באתרים שונים נטען. קוד ה-iframe טוען את ה-worklet, וה-worklet קורא ל-Private Aggregation API עם מזהה התוכן שהומר למפתח צבירת נתונים (קטגוריה).

contributeToHistogramOnEvent()

ב-worklets של Protected Audience API בלבד, אנחנו מספקים מנגנון מבוסס-טריגר לשליחת דוח רק אם מתרחש אירוע מסוים. הפונקציה הזו מאפשרת גם לקטגוריה ולערך להיות תלויים באותות שעדיין לא זמינים בשלב הזה במכרז.

השיטה privateAggregation.contributeToHistogramOnEvent(eventType, contribution) מקבלת eventType שמציין את האירוע שהפעיל את הבקשה, ואת contribution שצריך לשלוח כשהאירוע מופעל. אירוע ההפעלה יכול להגיע מהמכרז עצמו אחרי סיום המכרז, למשל אירוע של זכייה או הפסד במכרז, או שהוא יכול להגיע ממסגרת מוקפת גדר שדרכה המודעה הוצגה.

כדי לשלוח דוח על אירועי מכרזים, אפשר להשתמש בשתי מילות מפתח שמורות, reserved.win ו-reserved.loss ו-reserved.always. כדי לשלוח דוח שמופעל על ידי אירוע ממסגרת מגודר, צריך להגדיר סוג אירוע מותאם אישית. כדי להפעיל את האירוע ממסגרת מגודר, משתמשים בשיטה fence.reportEvent() שזמינה ב-Fenced Frames Ads Reporting API.

בדוגמה הבאה, מערכת Analytics שולחת דוח חשיפות כשהאירוע 'זכייה במכרז' מופעל, ושולחת דוח קליקים אם האירוע click מופעל מהמסגרת המגודרת שדרכה המודעה הוצגה. אפשר להשתמש בשני הערכים האלה כדי לחשב את שיעור הקליקים.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

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

enableDebugMode()

קובצי ה-cookie של צד שלישי עדיין זמינים, אבל אנחנו נספק מנגנון זמני שיאפשר לבצע ניפוי באגים ובדיקות בקלות רבה יותר על ידי הפעלת מצב ניפוי הבאגים. דוח ניפוי באגים שימושי להשוואה בין המדידות שמבוססות על קובצי cookie לבין המדידות של Private Aggregation. הוא גם מאפשר לאמת במהירות את השילוב של ה-API.

קריאה ל-privateAggregation.enableDebugMode() ב-worklet מפעילה את מצב ניפוי הבאגים, וכתוצאה מכך דוחות שניתן לצבור אותם כוללים את עומס העבודה (payload) ללא הצפנה (טקסט ללא הצפנה). לאחר מכן תוכלו לעבד את עומסי העבודה האלה באמצעות הכלי המקומי לבדיקות של Aggregation Service.

מצב ניפוי הבאגים זמין רק למבצעי קריאה (callers) שיש להם הרשאה לגשת לקובצי cookie של צד שלישי. אם למבצע הקריאה אין גישה לקובצי Cookie של צד שלישי, הקריאה ל-enableDebugMode() תיכשל ללא הודעה.

אפשר גם להגדיר את מפתח ניפוי הבאגים באמצעות קריאה ל-privateAggregation.enableDebugMode({ <debugKey: debugKey> }), כאשר אפשר להשתמש ב-BigInt כמפתח ניפוי באגים. אפשר להשתמש במפתח לניפוי באגים כדי לשייך נתונים ממדידה שמבוססת על קובצי cookie לנתונים ממדידה של Private Aggregation.

אפשר להפעיל אותם רק פעם אחת לכל הקשר. כל קריאה נוספת תגרום להשלכת חריגה.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

אימות הדוח

Private Aggregation API מאפשר מדידה בכמה אתרים בו-זמנית תוך שמירה על פרטיות המשתמשים. עם זאת, גורמים זדוניים עשויים לנסות לשנות את הדיוק של המדידות האלה. כדי למנוע זאת, אפשר להשתמש במזהה הקשר כדי לאמת את האותנטיות של הדוחות.

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

• מניעת דוחות לא חוקיים או לא אותנטיים: מוודאים שהדוחות נוצרים באמצעות קריאות API לגיטימיות ואותנטיות, וכך מקשים על גורמים זדוניים ליצור דוחות מזויפים.
• מניעת הפעלה חוזרת של דוחות: זיהוי ודחייה של כל ניסיון לשימוש חוזר בדוחות ישנים, כדי לוודא שכל דוח תורם רק פעם אחת לתוצאות המצטברות.

Shared Storage

כשמשתמשים ב-Shared Storage כדי להריץ פעולה שיכולה לשלוח דוח שניתן לצבור, אפשר להגדיר מזהה בלתי צפוי מחוץ ל-worklet.

המזהה הזה מוטמע בדוח שנוצר מה-worklet. אפשר לציין אותו בקריאה לשיטות של אחסון משותף run() או selectURL(), באובייקט האפשרויות, בקטע privateAggregationConfig.

לדוגמה:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

אחרי שמגדירים את המזהה הזה, אפשר להשתמש בו כדי לוודא שהדוח נשלח מהפעולה של האחסון המשותף. כדי למנוע זליגת מידע, נשלח רק דוח אחד לכל פעולה ב-Shared Storage (גם אם לא בוצעו הוספות), ללא קשר למספר הקריאות ל-contributeToHistogram().

Private Aggregation API שולח דוחות של נתונים נצברים עם עיכוב אקראי של עד שעה. עם זאת, הגדרת מזהה הקשר לאימות דוח מפחיתה את העיכוב הזה. במקרה כזה, יש עיכוב קבוע וקטן יותר של 5 שניות מהפעלת הפעולה של האחסון המשותף.

תהליך עבודה לדוגמה (כפי שמוצג בתרשים שלמעלה):

1. הפעולה של Shared Storage פועלת עם הגדרה של Private Aggregation שמציינת מזהה הקשר, ונוצר דוח שניתן לצבור.
2. מזהה ההקשר מוטמע בדוח שנוצר ואפשר לצבור אותו, ונשלח לשרת שלכם.
3. השרת אוסף את הדוחות שנוצרו ואפשר לצבור אותם.
4. תהליכים בשרת בודקים את מזהה ההקשר בכל דוח שאפשר לצבור, בהשוואה למזהי ההקשר השמורים, כדי לוודא שהוא תקין לפני שהדוחות מקובצים ונשלחים לשירות הצבירה.

אימות מזהה הקשר

יש כמה דרכים לאמת דוחות נכנסים לשרת האיסוף לפני שהם נשלחים ל-Aggregation Service. יכול להיות שנדחה דוחות עם מזהי הקשר לא חוקיים אם מזהה ההקשר:

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

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

Private Aggregation API נמצא כרגע בתהליכי דיון ועשוי להשתנות בעתיד. אם תנסו את ה-API הזה ותהיה לכם משוב, נשמח לשמוע אותו.

• GitHub: קוראים את הסבר, שואלים שאלות ומשתתפים בדיון.
• תמיכה למפתחים: אפשר לשאול שאלות ולהצטרף לדיוני המאגר של תמיכת המפתחים של ארגז החול לפרטיות.
• הצטרפו לקבוצה של Shared Storage API ולקבוצה של Protected Audience API כדי לקבל את ההודעות האחרונות בקשר לצבירת נתונים פרטית.