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

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

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

סטטוס ההטמעה

מהו Private Aggregation API

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

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

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

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

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

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

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

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

בדיקת ה-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 לשימוש כללי למדידת ביצועים בכמה אתרים, ואפשר להשתמש בו ב-worklets של Shared Storage ושל Protected Audience API. השלב הראשון הוא להחליט מה בדיוק אתם רוצים לאסוף. נקודות הנתונים האלה הן הבסיס למפתחות הצבירה.

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

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

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

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

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

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

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

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

מדידת תדירות של K+

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

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

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

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

באמצעות Protected Audience API

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

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

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

הפונקציות הבאות זמינות באובייקט privateAggregation שזמין ב-worklets של אחסון משותף ו-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()

בתוך רכיבי ה-worklet של 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
  });

מידע נוסף זמין במאמר הסבר על דיווח על צבירה פרטית מורחבת.

enableDebugMode()

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

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

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

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

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

// Enables debug mode
privateAggregation.enableDebugMode();

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

אימות הדוח

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

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

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

Shared Storage

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

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

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

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

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

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

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