יצירת דוחות נתונים נצברים באמצעות נתונים מ-Protected Audience API ונתונים מאתרים שונים מ-Shared Storage.
כדי לספק תכונות קריטיות שהאינטרנט מסתמך עליהן, אתר הצבירה הפרטית ה-API תוכנן לצבירה ולדיווח על נתונים מאתרים שונים תוך שמירה על הפרטיות.
סטטוס הטמעה
הצעה | סטטוס |
---|---|
מניעת דוחות לא חוקיים של Private Aggregation API באמצעות אימות דוחות של Shared Storage הסבר |
זמינות ב-Chrome |
הזמינות של מצב ניפוי באגים באתר צבירה פרטית תלויה בכשירות של צדדים שלישיים בעיה ב-GitHub |
זמינות ב-Chrome M119 |
צמצום העיכוב בדיווח הסברים |
זמינות ב-Chrome M119 |
תמיכה ב-Private Aggregation API ובשירות צבירת נתונים ב-Google Cloud הסברים |
זמינות ב-Chrome M121 |
מרווח פנימי למטענים ייעודיים (payloads) של דוחות הסברים |
זמינות ב-Chrome M119 |
מצב ניפוי באגים באמצעות צבירה פרטית זמין לדיווח מסוג auctionReportBuyers הסברים |
צפויות בחירות ב-Chrome M123 |
תמיכה במזהה סינון הסברים |
צפויות בחירות ב-Chrome M128 |
מהו Private Aggregation API
Private Aggregation API מאפשר למפתחים ליצור דוחות נתונים נצברים עם נתונים מ-Protected Audience API נתונים מאתרים שונים מאחסון משותף.
הפונקציה העיקרית של ה-API הזה נקראת contributeToHistogram()
. פעולת ההיסטוגרמה מאפשרת לכם לצבור נתונים
משתמשים שונים בכל קטגוריה (שנקראת ב-API כמפתח צבירה) שמגדירים.
קריאת ההיסטוגרמה צוברת ערכים ומחזירה תוצאה מצטברת עם רעש
בצורה של דוח סיכום. לדוגמה, הדוח עשוי להציג את מספר
אתרים שכל משתמש ראה בהם את התוכן שלך, או שנתקל בבאג בסקריפט של הצד השלישי. הפעולה הזו מתבצעת ב-worklet של API אחר.
לדוגמה, אם תיעדתם בעבר נתונים דמוגרפיים ונתונים גיאוגרפיים ב-Shared Storage, אתם יכולים להשתמש ב-Private Aggregation API כדי ליצור היסטוגרמה שמראה כמה בערך המשתמשים בניו יורק ראו את התוכן שלכם באתרים שונים. כדי לצבור נתונים למדידה הזו, אפשר לקודד את מאפיין המיקום הגיאוגרפי למפתח הצבירה ולספור את המשתמשים בערך המצטבר.
מושגים מרכזיים
כשקוראים ל-Private Aggregation API עם מפתח צבירה ועם ערך נצבר, הדפדפן יוצר דוח מצטבר.
דוחות נצברים נשלחים לשרת שלכם לצורך איסוף וקיבוץ. עיבוד הדוחות באצווה מתבצע מאוחר יותר על ידי שירות הצבירה, ונוצר דוח סיכום.
במסמך בנושא היסודות של ה-API לצבירה פרטית תוכלו לקרוא מידע נוסף על המושגים המרכזיים של Private Aggregation API.
הבדלים לעומת דוחות השיוך (Attribution)
יש הרבה דמיון בין Private Aggregation API ל-Attribution Reporting API. דוחות שיוך (Attribution) הם ממשק API עצמאי למדידת המרות, ואילו צבירת נתונים פרטית מיועדת למדידות באתרים שונים בשילוב עם ממשקי API, כמו Protected Audience API ו-Shared Storage. שני ממשקי ה-API מפיקים דוחות נצברים שנעשה בהם שימוש בקצה העורפי של שירות הצבירה כדי ליצור דוחות סיכום.
דוחות שיוך (Attribution) משייכים נתונים שנאספו מאירוע חשיפה ומאירוע המרה, שמתרחשים בזמנים שונים. מדד צבירה פרטית מודד אירוע יחיד בכמה אתרים.
בדיקת ה-API הזה
כדי לבדוק את Private Aggregation API באופן מקומי, צריך להפעיל את כל ממשקי ה-API לשמירה על פרטיות בפרסום בדומיין chrome://settings/adPrivacy
.
למידע נוסף על בדיקה בקטע ניסוי והשתתפות.
שימוש בהדגמה
אפשר לגשת להדגמה של Private Aggregation API for Shared Storage בכתובת goo.gle/shared-storage-demo, והקוד זמין ב-GitHub. ההדגמה מטמיעה את הפעולות בצד הלקוח ומפיקה דוח נצברים שנשלח לשרת שלכם.
בעתיד תפורסם הדגמה של Private Aggregation API ל-Protected Audience API.
תרחישים לדוגמה
Private Aggregation הוא API לשימוש כללי למדידה באתרים שונים, והוא זמין לשימוש ב-worklets של Shared Storage (אחסון משותף) ו-Protected Audience API. השלב הראשון הוא להחליט באופן ספציפי איזה מידע רוצים לאסוף. נקודות הנתונים האלה הן הבסיס למפתחות הצבירה שלכם.
עם נפח אחסון משותף
אחסון משותף מאפשר לקרוא ולכתוב נתונים מאתרים שונים בסביבה מאובטחת כדי למנוע דליפה, ו-Private Aggregation API מאפשר למדוד נתונים מאתרים שונים שמאוחסנים באחסון משותף.
מדידה של היקף החשיפה למשתמשים ייחודיים
כדאי למדוד כמה משתמשים ייחודיים ראו את התוכן שלהם. Private Aggregation API יכול לתת תשובה כמו "כ-317 משתמשים ייחודיים ראו את מערכת Content ID 861".
תוכלו להגדיר דגל ב-Shared Storage כדי לציין אם המשתמש כבר ראה את התוכן. בביקור הראשון שבו הדגל לא קיים, מתבצעת קריאה לצבירה פרטית ולאחר מכן הדגל מוגדר. בביקורים הבאים של המשתמש, כולל כניסות בין אתרים, ניתן לבדוק את 'נפח אחסון משותף' ולדלג על שליחת דוח לצבירת נתונים פרטיים, אם הדגל מוגדר. בסקירה המפורטת על היקף החשיפה תוכלו למצוא מידע נוסף על השיטות להטמעת המדידות האלה.
מדידה של מידע דמוגרפי
כדאי למדוד את הדמוגרפיה של המשתמשים שצפו בתוכן שלכם באתרים שונים.
צבירת נתונים פרטית יכולה לספק תשובה, למשל "כ-317 משתמשים ייחודיים הם בגילאי 18-45 והם מגרמניה". השתמשו באחסון משותף כדי לגשת לנתונים דמוגרפיים מהקשר של צד שלישי. בשלב מאוחר יותר, תוכלו ליצור דוח עם 'צבירה פרטית'. כדי לעשות את זה, מקודדים את המאפיינים של קבוצת הגיל והמדינה במפתח הצבירה.
מדידת תדירות של K+
כדאי למדוד את מספר המשתמשים שראו קטע תוכן או מודעה לפחות K פעמים בדפדפן נתון, לפי ערך שנבחר מראש: K.
באמצעות צבירת נתונים פרטית אפשר לקבל תשובה כמו "כ-89 משתמשים ראו את מערכת Content ID 581 לפחות 3 פעמים". אפשר להגדיל מונה ב-Shared Storage מאתרים שונים, ואפשר לקרוא אותו ב-worklet. כשהמספר יגיע ל-K, ניתן יהיה לשלוח דוח באמצעות 'צבירה פרטית'.
באמצעות Protected Audience API
Protected Audience API מאפשר טירגוט מחדש ותרחישים לדוגמה לקהלים בהתאמה אישית, וצבירה פרטית מאפשרת לדווח על אירועים מ-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 this.sharedStorage.get(key) === 'true';
// Do not 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 this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
בדוגמת הקוד שלמעלה, המערכת תקרא 'צבירה פרטית' בכל פעם שתוכן iframe חוצה-אתרים ייטען. קוד ה-iframe טוען את ה-worklet ו-worklet קורא ל-Private Aggregation API כשמזהה התוכן מומר למפתח צבירה (קטגוריה).
contributeToHistogramOnEvent()
רק אם מתרחש אירוע מסוים, אנחנו מספקים מנגנון מבוסס-טריגר לשליחת דוח ב-Protected Audience API. הפונקציה הזו גם מאפשרת שהקטגוריה והערך יהיו תלויים באותות שעדיין לא זמינים באותו שלב במכרז.
השיטה privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
מקבלת ערך eventType
שמציין את האירוע המפעיל, ואת contribution
כאשר האירוע מופעל. האירוע שגרם להפעלת המכרז יכול להגיע מהמכרז עצמו אחרי שהמכרז מסתיים. למשל, זכייה במכרז או אירוע הפסד, או שהוא עשוי להגיע ממסגרת מוגדרת שגרמה להצגת המודעה.
כדי לשלוח דוח של אירועי מכרז, אפשר להשתמש בשתי מילות מפתח שמורות: reserved.win
, reserved.loss
ו-reserved.always
. כדי לשלוח דוח שמופעל על ידי אירוע במסגרת מגודרת, צריך להגדיר סוג אירוע בהתאמה אישית. כדי להפעיל את האירוע ממסגרת מגודרת, צריך להשתמש בשיטה fence.reportEvent()
שזמינה מ-Fenced Frames Ads Reporting API.
בדוגמה הבאה נשלח דוח חשיפות כשהאירוע של זכייה במכרז מופעל, ודוח קליקים אם מופעל אירוע 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
});
מידע נוסף זמין בהודעת ההסבר בנושא דיווח מורחב על צבירה פרטית.
enableDebugMode()
קובצי Cookie של צד שלישי עדיין זמינים, אבל אנחנו נספק מנגנון זמני שמאפשר להפעיל את מצב ניפוי הבאגים כדי להקל על ניפוי באגים ובדיקה. דוח ניפוי באגים שימושי להשוואה בין המדידות שמבוססות על קובצי cookie למדידות של הצבירה הפרטית, והוא גם מאפשר לאמת במהירות את השילוב של ה-API.
קריאה ל-privateAggregation.enableDebugMode()
ב-worklet מפעילה את מצב ניפוי הבאגים שגורם לדוחות נצברים לכלול את המטען הייעודי (payload) הלא מוצפן (cleartext). לאחר מכן תוכלו לעבד את מטענים ייעודיים (payloads) האלה באמצעות כלי הבדיקה המקומי של שירות הצבירה.
מצב ניפוי הבאגים זמין רק למתקשרים עם הרשאת גישה
קובצי Cookie של צד שלישי. אם למבצע הקריאה אין גישה לקובצי Cookie של צד שלישי,
המכשיר enableDebugMode()
ייכשל בלי להציג אזהרה או שגיאה. כלומר, כשצד שלישי
קובצי cookie הוצאו משימוש. מצב ניפוי הבאגים לא יהיה זמין יותר.
אפשר גם להגדיר את מפתח ניפוי הבאגים על ידי שליחת קריאה ל-privateAggregation.enableDebugMode({ <debugKey: debugKey> })
, כאשר BigInt
יכול לשמש כמפתח לניפוי באגים. אפשר להשתמש במפתח ניפוי הבאגים כדי לשייך נתונים ממדידה שמבוססת על קובצי cookie ונתונים ממדידה של צבירת נתונים פרטית.
אפשר לקרוא את הפרמטרים האלה רק פעם אחת לכל הקשר. כל שיחה עתידית תגרום לחריגה.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
דיווח על אימות
עבור Shared Storage, כדי לוודא שהדוחות המצטברים שקיבלתם הם לגיטימיים, על ידי הוספת מזהה הקשר לקריאה לפעולה של האחסון המשותף. המזהה יצורף לדוח שנשלח, ובהמשך תוכלו להשתמש במזהה הזה כדי לאמת שהדוח נשלח מפעולת האחסון המשותף.
מידע נוסף זמין בהסבר על אימות הדיווח.
מעורבות ושיתוף משוב
ה-Private Aggregation API נמצא בדיון פעיל ועשוי להשתנות בעתיד. אם ניסיתם את ה-API הזה ויש לכם משוב, נשמח לשמוע אותו.
- GitHub: קוראים את ההסבר, מעלים שאלות ומשתתפים בדיון.
- תמיכה למפתחים: אפשר לשאול שאלות ולהצטרף לדיונים במאגר התמיכה למפתחים של 'ארגז החול לפרטיות'.
- כדי לקבל את ההודעות האחרונות שקשורות לצבירה פרטית, מצטרפים לקבוצת Shared Storage API ולקבוצת Protected Audience API.