דף זה תורגם על ידי Cloud Translation API.

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

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

קהל היעד: ספקי טכנולוגיות פרסום ומדידה.

הפעל את ההדגמה

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

צבירה פרטית
- מדידת היקף החשיפה למשתמשים ייחודיים
- מדידה של מידע דמוגרפי
- מדידת התדירות של K+
שימוש כללי
- מדידת אירוע של העברת עכבר מעל מסגרות מגודרות
- ניווט ברמה עליונה
- שליטה במקומות שבהם צדדים שלישיים יכולים לכתוב

איך מציגים נפח אחסון משותף

כדי לראות מה נשמר באחסון משותף, צריך להשתמש בכלי הפיתוח ל-Chrome. ניתן למצוא נתונים מאוחסנים ב-Application -> Shared Storage.

הצגת נתונים שמאוחסנים באחסון משותף באמצעות כלי הפיתוח ל-Chrome.

הצגת דוחות של צבירת נתונים פרטית

כדי להציג את הדוחות המצטברים שנשלחו, עוברים אל chrome://private-aggregation-internals. כשמצב ניפוי הבאגים מופעל, הדוח נשלח באופן מיידי (ללא השהיה) לכתובת [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage, יחד עם הדוח 'עיכוב הזמן' שיישלח אל [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

כדי להפעיל את ניפוי הבאגים, פועלים לפי ההוראות בקטע ניפוי באגים.

הצגת דוחות בכתובת chrome://private-aggregation-internals.

ממשק API של Shared Storage

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

נפח האחסון המשותף מוגבל למקור ההקשר (מבצע הקריאה של sharedStorage).

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

חשבונית של נפח אחסון משותף

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

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

בקטע Proposed API Surface – in the worklet תוכלו למצוא את השיטות שנעשה בהן שימוש ב-worklet במהלך הפעולה.
שימוש בכותרות של תשובות

התכונה הזו הפכה לזמינה בגרסה M119.

בדומה ל-JavaScript, אפשר להשתמש בכותרות תגובות רק לפונקציות ספציפיות כמו הגדרה, הוספה ומחיקה של ערכים באחסון משותף. כדי להשתמש בנפח אחסון משותף בכותרת תגובה, צריך לכלול את Shared-Storage-Writable: ?1 בכותרת הבקשה.

על מנת להתחיל בקשה מהלקוח, מריצים את הקוד הבא, בהתאם לשיטה שבחרתם:
- שימוש ב-fetch()
```
fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
```
- באמצעות תג iframe או img
```
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
```
- שימוש במאפיין IDL עם תג iframe או img
```
let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";
```

מידע נוסף זמין במאמר Shared Storage: כותרת תגובה.

כתיבה באחסון משותף

כדי לכתוב באחסון משותף, צריך להפעיל את sharedStorage.set() מתוך ה-worklet של JavaScript או מחוצה לו. אם מפעילים קריאה מחוץ ל-worklet, הנתונים נכתבים למקור של הקשר הגלישה שממנו בוצעה הקריאה. אם קוראים לזה מתוך ה-worklet, הנתונים נכתבים למקור של הקשר הגלישה שטען את ה-worklet. למפתחות שהוגדרו יש תאריך תפוגה של 30 יום מהעדכון האחרון.

השדה ignoreIfPresent הוא אופציונלי. אם הוא קיים ומוגדר ל-true, המפתח לא מתעדכן אם הוא כבר קיים. תאריך התפוגה של המפתח מתחדש ל-30 יום לאחר הקריאה ל-set(), גם אם המפתח לא עודכן.

אם ניגשים ל-Shared Storage מספר פעמים באותה טעינת דף עם אותו מפתח, הערך של המפתח יוחלף. כדאי להשתמש ב-sharedStorage.append() אם המפתח צריך לשמור על הערך הקודם.

באמצעות JavaScript

מחוץ ל-worklet:

window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
// Shared Storage: {'myKey': 'myValue2'}

באופן דומה, בתוך ה-worklet:

sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });

שימוש בכותרות של תשובות

אפשר גם לכתוב בתיקייה 'אחסון משותף' באמצעות כותרות של תשובות. כדי לעשות זאת, השתמשו ב-Shared-Storage-Write בכותרת התגובה יחד עם הפקודות הבאות:
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
```
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
```
אפשר להפריד בין כמה פריטים באמצעות פסיקים, והם יכולים לשלב בין set, append, delete ו-clear.
```
Shared-Storage-Write : 
set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
```

צירוף ערך

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

באמצעות JavaScript

כדי לעדכן ערכים של מפתחות קיימים, צריך להשתמש ב-sharedStorage.append() בתוך ה-worklet או מחוץ לו.

window.sharedStorage.append('myKey', 'myValue1');
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.append('myKey', 'myValue2');
// Shared Storage: {'myKey': 'myValue1myValue2'}
window.sharedStorage.append('anotherKey', 'hello');
// Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}

כדי להוסיף בתוך ה-worklet:

sharedStorage.append('myKey', 'myValue1');

שימוש בכותרות של תשובות

בדומה להגדרת ערך באחסון משותף, אפשר להשתמש בערך Shared-Storage-Write בכותרת התגובה כדי להעביר את הזוג מפתח/ערך.
```
Shared-Storage-Write : append;key="myKey";value="myValue2"
```

קריאה מנפח אחסון משותף

אפשר לקרוא מ-Shared Storage רק מתוך worklet.

await sharedStorage.get('mykey');

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

מתבצעת מחיקה מאחסון משותף

אפשר לבצע מחיקות מ-Shared Storage באמצעות JavaScript בתוך ה-worklet או מחוצה לו, או באמצעות כותרות תגובה עם delete(). כדי למחוק את כל המפתחות בבת אחת, יש להשתמש ב-clear() מאחד מהם.

באמצעות JavaScript

כדי למחוק מ'אחסון משותף' מחוץ ל-worklet:
```
window.sharedStorage.delete('myKey');
```
כדי למחוק מ'אחסון משותף' מתוך ה-worklet:
```
sharedStorage.delete('myKey');
```
כדי למחוק את כל המפתחות בבת אחת מחוץ ל-worklet:
```
window.sharedStorage.clear();
```
כדי למחוק את כל המפתחות בבת אחת מתוך ה-worklet:
```
sharedStorage.clear();
```
שימוש בכותרות של תשובות

כדי למחוק ערכים באמצעות כותרות תגובה, אפשר גם להשתמש ב-Shared-Storage-Write בכותרת התגובה כדי להעביר את המפתח למחיקה.
```
delete;key="myKey"
```
כדי למחוק את כל המפתחות באמצעות כותרות התגובות:
```
clear;
```

החלפת הקשר

נתוני נפח האחסון המשותף נכתבים ב-origin (לדוגמה, https://example.adtech.com) של הקשר הגלישה שממנו הגיעה הקריאה.

כשטוענים את הקוד של צד שלישי באמצעות תג <script>, הקוד מופעל בהקשר של גלישה במטמיע. לכן, כשהקוד של הצד השלישי קורא ל-sharedStorage.set(), הנתונים נכתבים באחסון המשותף של המטמיע. כשטוענים את הקוד של צד שלישי בתוך iframe, הקוד מקבל הקשר גלישה חדש והמקור שלו הוא המקור של ה-iframe. לכן, הקריאה sharedStorage.set() מה-iframe מאחסנת את הנתונים באחסון המשותף של מקור ה-iframe.

נתונים שנאספים ישירות ממשתמשים

אם בדף מהאינטראקציה הישירה מוטמע קוד JavaScript של צד שלישי שקורא ל-sharedStorage.set() או ל-sharedStorage.delete(), צמד המפתח/ערך מאוחסן בהקשר של הצד הראשון.

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

הקשר של צד שלישי

אפשר לשמור את צמד המפתח/ערך בהקשר של טכנולוגיית המודעות או בהקשר של צד שלישי, על ידי יצירת iframe וקריאה ל-set() או ל-delete() בקוד ה-JavaScript מתוך ה-iframe.

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

API לצבירה פרטית

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

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

כדי להגן על הפרטיות, המטען הייעודי (payload) של הדוח, שכולל את הקטגוריה והערך, מוצפן בזמן ההעברה, ואפשר לפענח אותו ולקבץ אותו רק באמצעות שירות הצבירה.

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

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

הפעלת אחסון משותף וצבירה פרטית

ב-iframe של המודעה, טוענים את מודול worklet על ידי קריאה ל-addModule(). כדי להריץ את השיטה שרשומה בקובץ worklet של sharedStorageWorklet.js, באותו JavaScript של iframe של מודעה, צריך לקרוא ל-sharedStorage.run().

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

בסקריפט של worklet, תצטרכו ליצור מחלקה עם method run אסינכרונית. וregister את המחלקה הזו להפעלה ב-iframe של המודעה. בתוך sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

ניפוי באגים

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

privateAggregation.enableDebugMode();

כדי לשייך את הדוחות להקשרים שהקפיצו אותם, תוכלו להגדיר מפתח ניפוי באגים מסוג 'מספר שלם לא חתום' באורך 64 ביט שמועבר לקריאת JavaScript. הערך בעמודה debugKey הוא BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

ניפוי באגים באחסון משותף

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

Promise is rejected without and explicit error message

אתם יכולים לנפות באגים באחסון משותף על ידי אריזת הקריאות עם בלוקים של try-catch.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

ניפוי באגים בצבירה פרטית

הדוחות נשלחים ל-/.well-known/private-aggregation/report-shared-storage ול-/.well-known/private-aggregation/debug/report-shared-storage. דוחות ניפוי הבאגים מקבלים מטען ייעודי (payload) שדומה לקובץ ה-JSON הבא. המטען הייעודי (payload) הזה מגדיר את השדה api כ'אחסון משותף'.

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

מטען ייעודי (payload) של ניפוי באגים

השדה debug_cleartext_payload מקודד ב-Base64 CBOR. אפשר להציג את הקטגוריה והערך באמצעות המפענח, או להשתמש בקוד JavaScript שנמצא במפענח אחסון משותף.

השלבים הבאים

בדפים הבאים מוסברים היבטים חשובים של ממשקי ה-API של אחסון משותף ושל צבירה פרטית.

אחרי שאתם מכירים את ממשקי ה-API, אפשר להתחיל לאסוף את הדוחות, שיישלחו כבקשת POST לנקודות הקצה הבאות כ-JSON בגוף הבקשה.

דוחות ניפוי באגים – context-origin/.well-known/private-aggregation/debug/report-shared-storage
דוחות – context-origin/.well-known/private-aggregation/report-shared-storage

אחרי שאוספים את הדוחות, אפשר לבצע את הבדיקה באמצעות כלי הבדיקה המקומי או להגדיר את Trusted Execution Environment for Aggregation Service על מנת לקבל את הדוחות הנצברים.

שיתוף משוב

אתם יכולים לשתף את המשוב שלכם על ממשקי ה-API והתיעוד ב-GitHub.