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

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

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

סטטוס ההטמעה

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

מהו Private Aggregation API

Private Aggregation API מאפשר למפתחים ליצור דוחות נתונים נצברים עם נתונים מ-Protected Audience API נתונים מאתרים שונים מאחסון משותף.

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

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

מדידה דמוגרפית

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

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

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

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

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

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

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

באמצעות 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 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

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