מושגי מפתח של 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 עם מפתח צבירה ערך מצטבר, הדפדפן יוצר דוח מצטבר. הדוחות נשלחים לשרת שלכם שמקבץ את הדוחות. הדוחות באצווה מעובדת מאוחר יותר על ידי שירות הצבירה, ומופק דוח סיכום.
![הנתונים עוברים מהלקוח לאוסף ואז אל הצבירה
שירות ליצירת דוח סיכום.](https://developers.google.cn/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=9&hl=he)
- כשקוראים ל-Private Aggregation API, הלקוח (הדפדפן) יוצר ושולח את הדוח המצטבר לשרת שלכם כדי שייאספו עליו נתונים.
- השרת אוסף את הדוחות מהלקוחות ומקבץ אותם כדי נשלח לשירות הצבירה.
- אחרי שתאספו מספיק דוחות, תחלקו אותם ותשלחו אותם אל שירות צבירה, שפועל בסביבת הפעלה מהימנה, כדי ליצור דוח סיכום.
תהליך העבודה שמתואר בקטע הזה דומה לדיווח שיוך (Attribution) API. אבל, השיוך הדיווח משייך נתונים שנאספו מאירוע חשיפה ומהמרה שמתרחש בזמנים שונים. באמצעות צבירה פרטית אירוע חוצה-אתרים.
מפתח צבירת נתונים
מפתח צבירה (בקיצור) מייצג את הקטגוריה שבה יצטברו ערכים נצברים. אפשר לקודד מאפיין אחד או יותר לתוך המפתח. מאפיין מייצג היבט מסוים שברצונך לקבל תובנות בנושא, כמו קבוצת הגיל של המשתמשים או מספר החשיפות של מודעה .
לדוגמה, נניח שיש לכם ווידג'ט שמוטמע בכמה אתרים אם אתם רוצים לנתח את המדינה של המשתמשים שראו את הווידג'ט שלכם. אתה מחפש כדי לענות על שאלות כמו "כמה מהמשתמשים שראו את הווידג'ט שלי מ-Country X? " כדי לדווח על השאלה הזו, אפשר להגדיר מפתח צבירה שמקודדים שני מאפיינים: מזהה ווידג'ט ומזהה מדינה.
המפתח שסופק ל-Private Aggregation API הוא
BigInt,
שמורכב מכמה מאפיינים. בדוגמה הזאת, המאפיינים הם
מזהה הווידג'ט ומזהה המדינה. נניח שמזהה הווידג'ט יכול להכיל עד 4 ספרות
ארוך כמו 1234
, וכל מדינה ממופה למספר מסוים בסדר אלפביתי
הזמנה כמו אפגניסטן היא 1
, צרפת היא 61
וזימבבואה הוא '195'.
לכן, המפתח המצטבר יהיה באורך של 7 ספרות, כאשר 4
התווים שמורים לWidgetID
ו-3 התווים האחרונים הם
שמורים ל-CountryID
.
נניח שהמפתח מייצג את מספר המשתמשים מצרפת (מזהה מדינה 061
)
שראו את מזהה הווידג'ט 3276
, מפתח הצבירה הוא 3276061
.
מפתח צבירת נתונים | |
מזהה ווידג'ט | מזהה מדינה |
3276 | 061 |
ניתן ליצור את מפתח הצבירה גם באמצעות מנגנון גיבוב, כמו
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
ערך צבירת נתונים
הערכים הנצברים מסוכמים לכל מפתח ממשתמשים רבים כדי ליצור כמו ערכי סיכום בדוחות הסיכום.
עכשיו נחזור לשאלה לדוגמה שהוצגה למעלה: "כמה משתמשים מי ראו את הווידג'ט שלי הם מצרפת?" התשובה לשאלה הזו תיראה משהו כמו "בערך 4881 משתמשים שראו את מזהה הווידג'ט 3276 שלי הם from France." הערך המצטבר הוא 1 לכל משתמש, ו-4881 משתמשים תואם לערך הערך הנצבר שהוא הסכום של כל הערכים הנצברים מפתח צבירה.
מפתח צבירת נתונים | ערך צבירת נתונים | |
מזהה ווידג'ט | מזהה מדינה | מספר צפיות |
3276 | 061 | 1 |
לצורך הדוגמה הזו, אנחנו מעלים את הערך ב-1 לכל משתמש שרואה את הווידג'ט. בפועל, אפשר להתאים את הערך המצטבר כדי לשפר את האות לרעש יחס גובה-רוחב.
תקציב התרומות
כל קריאה ל-Private Aggregation API נקראת תרומה. להגנה פרטיות המשתמשים, מספר התרומות שניתן לאסוף לאדם מוגבל.
כאשר מחברים את כל הערכים המצטברים בכל מפתחות הצבירה, הסכום חייב יהיו נמוכות מהתקציב לתרומה. התקציב הוא בהיקף לפי עבודה origin, ליום, ו- בנפרד ל-Protected Audience API ול-worklets של Shared Storage. גלגול חלון של כ-24 השעות האחרונות משמש עבור היום. אם תג חדש דוח המצטבר יגרום לחריגה מהתקציב, נוצר.
תקציב התרומה מיוצג על ידי הפרמטר L1, מוגדר ל-216 (65,536) לעשר דקות ביום עם עצירת ביניים של 220
(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
:
![צילום מסך של דף המידע הפנימי של Private Aggregation API](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=9&hl=he)
למטרות בדיקה, העמודה "שליחת דוחות נבחרים" יכול לשמש לשליחת הלחצן לדווח לשרת באופן מיידי.
איסוף וקיבוץ של דוחות נצברים
הדפדפן שולח את הדוחות המצטברים למקור של ה-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
![השירות פועל בסביבת TEE, מפענח את הדוחות המצטברים ומוסיף
רעש כדי ליצור את דוח הסיכום הסופי.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=9&hl=he)
שירות הצבירה מקבל דוחות נצברים מוצפנים מהאוסף ויוצר סיכום דוחות.
כדי לפענח את המטען הייעודי (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 יהיה יחס אות לרעש גבוה בהרבה.
לכן, הכפלת הערך המצטבר בגורם הגדלה יכולה לעזור להפחית את הרעש. גורם קנה המידה מייצג את המידה שבה ברצונך להתאים את הגודל כערך מצטבר.
![הרעש הוא קבוע, ללא קשר לערך המצטבר.](https://developers.google.cn/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=9&hl=he)
העלאת הערכים על ידי בחירת גורם הגדלה גדול יותר מפחיתה את הסיכוי רעשי רקע. עם זאת, הפעולה הזו גם גורמת לסך כל התכנים שנוספו בכל הקטגוריות כדי להגיע מהר יותר למגבלת התקציב לתרומות. העלאת הערכים כלפי מטה ב- בחירת גורם הגדלה קטן יותר באופן קבוע מגבירה את הרעש היחסי, אבל מפחיתה את הסיכון של הגעה למגבלת התקציב.
![שינוי הערך המצטבר לתקציב התרומה.](https://developers.google.cn/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=9&hl=he)
כדי לחשב גורם מתאים להגדלה, צריך לחלק את תקציב התרומה ב- הסכום המקסימלי של הערכים המצטברים בכל המפתחות.
למידע על תקציב התרומות תיעוד למידע נוסף.
מעורבות ושיתוף משוב
ה-Private Aggregation API נמצא בדיון פעיל וכפוף לשינויים לעתיד. אם ניסיתם את ה-API הזה ויש לכם משוב, נשמח לשמוע אותו.
- GitHub: קראו את הסברים, העלאת שאלות והשתתפות דיון. * תמיכה למפתחים: אפשר לשאול שאלות ולהצטרף לדיונים תמיכה למפתחים של 'ארגז החול לפרטיות' במאגר. * הצטרפו אל Shared Storage API קבוצה ו-Protected Audience API קבוצה כדי לקבל את ההודעות האחרונות שקשורות לצבירה פרטית.