היסודות של API לצבירה פרטית

מושגי מפתח של Private Aggregation API

למי המסמך הזה מיועד?

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

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

מונחי מפתח

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

• מפתח צבירה (שנקרא גם קטגוריה) הוא מוגדר מראש של נקודות נתונים. לדוגמה, ייתכן שתרצו איסוף קטגוריה של נתוני מיקום שבה הדפדפן מדווח על המדינה שם. מפתח צבירה עשוי להכיל יותר ממאפיין אחד (לדוגמה, המדינה והמזהה של ווידג'ט התוכן).
• ערך מצטבר הוא נקודה על הגרף. שנאספים למפתח צבירה. אם אתם רוצים למדוד כמה משתמשים מצרפת ראו את התוכן שלך, אז France הוא מאפיין מפתח צבירה, וה-viewCount של 1 הוא הערך המצטבר.
• דוחות נצברים נוצרים ומוצפנים בתוך דפדפן. עבור Private Aggregation API, שמכיל נתונים על אירוע יחיד.
• שירות הצבירה מעבד נתונים מדוחות נצברים כדי ליצור דוח סיכום.
• דוח סיכום הוא הפלט הסופי של שירות הצבירה. הדוח כולל נתוני משתמשים נצברים ונתוני המרות מפורטים.
• worklet הוא קטע של תשתית שמאפשרת להריץ פונקציות JavaScript ספציפיות להחזיר מידע למבקש. ב-worklet אפשר לבצע JavaScript, אבל לא ניתן לקיים אינטראקציה או לתקשר עם הדף החיצוני.

תהליך עבודה של צבירת נתונים פרטית

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

1. כשקוראים ל-Private Aggregation API, הלקוח (הדפדפן) יוצר ושולח את הדוח המצטבר לשרת שלכם כדי שייאספו עליו נתונים.
2. השרת אוסף את הדוחות מהלקוחות ומקבץ אותם כדי נשלח לשירות הצבירה.
3. אחרי שתאספו מספיק דוחות, תחלקו אותם ותשלחו אותם אל שירות צבירה, שפועל בסביבת הפעלה מהימנה, כדי ליצור דוח סיכום.

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

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

מפתח צבירת נתונים

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

לדוגמה, נניח שיש לכם ווידג'ט שמוטמע בכמה אתרים אם אתם רוצים לנתח את המדינה של המשתמשים שראו את הווידג'ט שלכם. אתה מחפש כדי לענות על שאלות כמו "כמה מהמשתמשים שראו את הווידג'ט שלי מ-Country X? " כדי לדווח על השאלה הזו, אפשר להגדיר מפתח צבירה שמקודדים שני מאפיינים: מזהה ווידג'ט ומזהה מדינה.

המפתח שסופק ל-Private Aggregation API הוא BigInt, שמורכב מכמה מאפיינים. בדוגמה הזאת, המאפיינים הם מזהה הווידג'ט ומזהה המדינה. נניח שמזהה הווידג'ט יכול להכיל עד 4 ספרות ארוך כמו 1234, וכל מדינה ממופה למספר מסוים בסדר אלפביתי הזמנה כמו אפגניסטן היא 1, צרפת היא 61 וזימבבואה הוא '195'. לכן, המפתח המצטבר יהיה באורך של 7 ספרות, כאשר 4 התווים שמורים לWidgetID ו-3 התווים האחרונים הם שמורים ל-CountryID.

נניח שהמפתח מייצג את מספר המשתמשים מצרפת (מזהה מדינה 061) שראו את מזהה הווידג'ט 3276, מפתח הצבירה הוא 3276061.

מפתח צבירת נתונים
מזהה ווידג'ט	מזהה מדינה
3276	061

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

ניתן ליצור את מפתח הצבירה גם באמצעות מנגנון גיבוב, כמו SHA-256. לדוגמה, המחרוזת אפשר לבצע גיבוב של {"WidgetId":3276,"CountryID":67} ואז להמיר אותו ערך של BigInt של 42943797454801331377966796057547478208888578253058197330928948081739249096287n. אם ערך הגיבוב כולל יותר מ-128 ביטים, אפשר לחתוך אותו כדי להבטיח שהוא לא חריגה מהערך המקסימלי המותר של 2^128−1 בקטגוריה.

בתוך worklet של Shared Storage, אפשר לגשת crypto ו- TextEncoder מודולים שיכול לעזור לכם ליצור גיבוב. לקבלת מידע נוסף על יצירת גיבוב (hash), אפשר לעבור אל SubtleCrypto.digest() במצב פעיל MDN

הדוגמה הבאה מתארת איך אפשר ליצור מפתח קטגוריה ממפתח מגובב (hashed) ערך:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

הערה: למרות שהמושגים דומים, המפתח להיות בעלת מבנה שונה עבור Private Aggregation API מאשר Attribution Reporting API. לצבירה פרטית, המפתח המלא מצוין בו-זמנית בקריאה של JavaScript.

ערך צבירת נתונים

הערכים הנצברים מסוכמים לכל מפתח ממשתמשים רבים כדי ליצור כמו ערכי סיכום בדוחות הסיכום.

עכשיו נחזור לשאלה לדוגמה שהוצגה למעלה: "כמה משתמשים מי ראו את הווידג'ט שלי הם מצרפת?" התשובה לשאלה הזו תיראה משהו כמו "בערך 4881 משתמשים שראו את מזהה הווידג'ט 3276 שלי הם from France." הערך המצטבר הוא 1 לכל משתמש, ו-4881 משתמשים תואם לערך הערך הנצבר שהוא הסכום של כל הערכים הנצברים מפתח צבירה.

מפתח צבירת נתונים		ערך צבירת נתונים
מזהה ווידג'ט	מזהה מדינה	מספר צפיות
3276	061	1

לצורך הדוגמה הזו, אנחנו מעלים את הערך ב-1 לכל משתמש שרואה את הווידג'ט. בפועל, אפשר להתאים את הערך המצטבר כדי לשפר את האות לרעש יחס גובה-רוחב.

תקציב התרומות

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

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

תקציב התרומה מיוצג על ידי הפרמטר L₁, מוגדר ל-2¹⁶ (65,536) לעשר דקות ביום עם עצירת ביניים של 2²⁰

(1,048,576). לצפייה הסברים למידע נוסף על הפרמטרים האלה.

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

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

דוחות נצברים

אחרי שהמשתמש מפעיל את Private Aggregation API, הדפדפן יוצר דוחות נצברים שיעובדו על ידי שירות הצבירה בשלב מאוחר יותר זמן ליצור סיכום . דוח נצברים בפורמט JSON ומכיל רשימה מוצפנת של תכנים שנוספו, שכל אחד מהם הוא צמד {aggregation key, aggregatable value}. דוחות מצטברים נשלחים בעיכוב אקראי של עד שעה.

התוכן שנוסף מוצפן ולא ניתן לקרוא אותו מחוץ לשירות הצבירה. שירות הצבירה מפענח את הדוחות ומפיק דוח סיכום. למפתח ההצפנה של הדפדפן והמפתח לפענוח של נתוני הצבירה השירות מונפקת על ידי המתאם, שמשמש כשירות ניהול מפתחות. המתאם שומר רשימה של גיבובים בינאריים של תמונת השירות כדי לאמת שהמתקשר רשאי לקבל את מפתח הפענוח.

דוגמה לדוח נצברים עם ניפוי באגים מצב מופעל:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

ניתן לבחון את הדוחות המצטברים דף chrome://private-aggregation-internals:

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

איסוף וקיבוץ של דוחות נצברים

הדפדפן שולח את הדוחות המצטברים למקור של ה-worklet שמכיל את הקריאה ל-Private Aggregation API, באמצעות path:

• לנפח אחסון משותף: /.well-known/private-aggregation/report-shared-storage
• עבור Protected Audience API: /.well-known/private-aggregation/report-protected-audience

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

לאחר מכן השרת צריך לקבץ דוחות ולשלוח את קיבוץ הנתונים לצבירה שירות. יצירת קבוצות קבצים על סמך המידע שזמין בקובץ ללא הצפנה המטען הייעודי (payload) של הדוח המצטבר, כמו השדה shared_info. במצב אידיאלי, הקבוצות צריכות להכיל 100 דוחות או יותר לכל קבוצה.

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

Aggregation Service

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

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

דוחות סיכום

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

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

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

לדוגמה:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

רעש והתאמה לעומס (scaling)

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

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

לדוגמה, נניח שבהתפלגות הרעש יש סטיית תקן של 100. וממורכז ב-0. אם הערך שנאסף בדוח המצטבר (או 'ערך מצטבר') הוא רק 200, אז סטיית התקן של הרעש תהיה 50% מהערך המצטבר. אבל אם הערך המצטבר הוא 20,000, אז סטיית התקן של הרעש תהיה רק 0.5% מהערך המצטבר. כלומר, ערך מצטבר של 20,000 יהיה יחס אות לרעש גבוה בהרבה.

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

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

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

למידע על תקציב התרומות תיעוד למידע נוסף.

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

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

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