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

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

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

סטטוס הטמעה

הצעה סטטוס
למנוע דוחות לא חוקיים של Private Aggregation API באמצעות אימות דוח לנפח אחסון משותף
הסבר		 זמין ב-Chrome
הזמינות של מצב ניפוי באגים בצבירה פרטית תלויה בזכאות של 3PC
בעיה ב-GitHub		 זמין ב-Chrome M119
צמצום העיכוב בדיווח
הסבר		 זמין ב-Chrome M119
תמיכה ב-Private Aggregation API ובשירות צבירה ל-Google Cloud
הסבר		 זמין ב-Chrome M121
מרווח פנימי למטענים ייעודיים (payloads) של דוחות מצטברים
הסבר		 זמין ב-Chrome M119
מצב ניפוי באגים בצבירה פרטית זמין לדיווח על מכרזים קונים
הסבר		 השינויים הצפויים בגרסה M123 של Chrome
תמיכה בסינון מזהה
הסבר		 השקה ראשונית של Chrome ברבעון השני של 2024.

מהו Private Aggregation API

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

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

התכונה זמינה לבדיקה ב-Chrome מגרסה M114 ואילך. אימות הדיווח עבור Protected Audience API עדיין לא זמין לבדיקה.

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

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

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