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

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

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

סטטוס ההטמעה

מה זה Private Aggregation API

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

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

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

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

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

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

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

הבדלים מ-Attribution Reporting

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

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

בדיקת ה-API

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

מידע נוסף על בדיקות וניסויים

שימוש בהדגמה

אפשר לגשת להדגמה של Private Aggregation API ל-Shared Storage בכתובת 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 משתמשים צפו בתוכן עם מזהה 581 לפחות 3 פעמים". אפשר להגדיל מונה באחסון משותף מאתרים שונים, ולקרוא אותו ב-worklet. כשהספירה מגיעה ל-K, אפשר לשלוח דוח באמצעות Private Aggregation.

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

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

עם Protected Audience API

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

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

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

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

contributeToHistogram()

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

דוגמה לאופן שבו אפשר להפעיל את הפונקציה ב-Shared Storage למדידת היקף החשיפה:

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

כדי לשלוח דוח על אירועים במכרז, אפשר להשתמש בשלוש מילות מפתח שמורות: reserved.win,‏ reserved.loss ו-reserved.always. כדי לשלוח דוח שמופעל על ידי אירוע מתוך פריים עם גדר, צריך להגדיר סוג אירוע מותאם אישית. כדי להפעיל את האירוע מתוך fenced frame, צריך להשתמש בשיטה 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
  });

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

enableDebugMode()

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

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

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

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

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

// 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.

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

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

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

השתתפות ושיתוף משוב

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

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