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

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

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

Shared Storage API

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

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

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

הפעלת האחסון המשותף

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

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

Worklet משמש לאחסון ולחילוץ נתונים באמצעות Shared Storage API.

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

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

• שימוש בכותרות תגובה

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

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

  באופן דומה, בתוך הווידג'ט:

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

• שימוש בכותרות תגובה

  אפשר גם לכתוב ב-Shared Storage באמצעות כותרות תגובה. לשם כך, צריך להשתמש ב-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. אם המפתח לא קיים, קריאה ל-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, אפשר להשתמש ב-Shared-Storage-Write בכותרת התגובה כדי להעביר את צמד המפתח/ערך.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

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

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

await sharedStorage.get('mykey');

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

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

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

• שימוש ב-JavaScript

  כדי למחוק מ-Shared Storage מחוץ ל-worklet:

  window.sharedStorage.delete('myKey');
  

  כדי למחוק מ-Shared Storage מתוך ה-worklet:

  sharedStorage.delete('myKey');
  

  כדי למחוק את כל המפתחות בבת אחת מחוץ ל-worklet:

  window.sharedStorage.clear();
  

  כדי למחוק את כל המפתחות בבת אחת מתוך ה-worklet:

  sharedStorage.clear();
  

• שימוש בכותרות תגובה

  כדי למחוק ערכים באמצעות כותרות תגובה, אפשר גם להשתמש ב-Shared-Storage-Write בכותרת התגובה כדי להעביר את המפתח שרוצים למחוק.

  delete;key="myKey"
  

  כדי למחוק את כל המפתחות באמצעות כותרות תגובה:

  clear;
  

מעבר בין הקשרים

נתוני Shared Storage נכתבים במקור (לדוגמה, https://example.adtech.com) של הקשר הגלישה שממנו הגיעה הקריאה.

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

הקשר ביחס לאינטראקציה ישירה (First-Party)

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

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

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

Private Aggregation API

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

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

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

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

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

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

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

כדי לשנות את התנהגות ברירת המחדל צריך להגדיר את המאפיין dataOrigin כשקוראים ל-createWorklet.

• dataOrigin: "context-origin": (ברירת המחדל) הנתונים נשמרים במאגר המשותף של המקור של הקשר הגלישה שמפעיל את הקריאה.
• dataOrigin: "script-origin": הנתונים מאוחסנים באחסון המשותף של המקור של הסקריפט של ה-worklet. חשוב לזכור: כדי להפעיל את המצב הזה, צריך להביע הסכמה.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

כדי להביע הסכמה, כשמשתמשים ב-"script-origin", נקודת הקצה של הסקריפט תצטרך להגיב עם הכותרת Shared-Storage-Cross-Origin-Worklet-Allowed. חשוב לזכור שצריך להפעיל את CORS לבקשות ממקורות שונים.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

ההגדרה של 'dataOrigin' ב-'createWorklet() ' ושל יצירת worklet של מקורות שונים עם 'addModule() ' הפכה לזמינה בגרסה M130.

שימוש ב-iframe חוצה-מקורות

צריך iframe כדי להפעיל את ה-worklet של האחסון המשותף.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

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

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

שימוש בבקשה ממקורות שונים

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

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

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

נקודת הקצה (endpoint) של JavaScript ממקורות שונים תצטרך להשיב עם הכותרות Shared-Storage-Cross-Origin-Worklet-Allowed ולציין ש-CORS מופעל בבקשה.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

ל-worklets שנוצרו באמצעות createWorklet() יהיו selectURL ו-run(). הפונקציה addModule() לא זמינה לאפשרות הזו.

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

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

השלבים הבאים

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

• מבוא לאחסון משותף (גרסת Chrome למפתחים)
• תרחישים לדוגמה לאחסון משותף (גרסת Chrome למפתחים)
• מבוא לאגרגציה פרטית (גרסת Chrome למפתחים)
• הסבר על אחסון משותף (GitHub)
• הסבר על צבירת נתונים פרטית (GitHub)
• הדגמה של אחסון משותף וצבירה פרטית

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

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

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

שיתוף משוב

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

• Shared Storage
• צבירה פרטית