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

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

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

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

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

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

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

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

ההבדלים בין דוחות השיוך (Attribution)

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

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

בדיקת ה-API הזה

כדי לבדוק את ה-Private Aggregation API, אפשר להפעיל את סימון הניסוי של ממשקי ה-API של ארגז החול לפרטיות בכתובת chrome://flags/#privacy-sandbox-ads-apis.

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

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

שימוש בהדגמה

בכתובת goo.gle/shared-storage-demo תוכלו לקרוא את ההדגמה של Private Aggregation API לאחסון משותף, והקוד זמין ב-GitHub. בהדגמה הטמעת את הפעולות בצד הלקוח ותפיק דוח מצטבר שנשלח לשרת שלך.

בעתיד תפורסם הדגמה של Private Aggregation API ל-Protected Audience API.

תרחישים לדוגמה

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

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

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

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

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

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

מדידה של מידע דמוגרפי

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

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

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

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

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

עם Protected Audience API

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

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

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

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

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

השיטה privateAggregation.reportContributionForEvent(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) });

דיווח על אימות

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

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

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

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

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