חלק מהטכנולוגיות של ארגז החול לפרטיות יוצאות משימוש.

אפשר לעיין בעדכון שלנו בנושא התוכניות לשימוש בטכנולוגיות של ארגז החול לפרטיות.

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

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

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

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

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

Shared Storage API

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

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

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

הפעלת Shared Storage

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

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

אפשר למצוא את ה-methods שמשמשים ב-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: Response Headers.

כתיבה ל-Shared Storage

כדי לכתוב ל-Shared Storage, קוראים ל-sharedStorage.set() מתוך JavaScript worklet או מחוצה לו. אם הקריאה מתבצעת מחוץ ל-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'}

באופן דומה, בתוך ה-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. אם המפתח לא קיים, קריאה ל-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'}

כדי להוסיף בסוף הוורקלט:

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

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

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

עדכון ערכים בחבילה

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

אפשר להתקשר אל batchUpdate() מ-JavaScript, או להשתמש בכותרת תגובה:

שימוש ב-JavaScript

שיטות JavaScript שאפשר להשתמש בהן עם batchUpdate() כוללות:
- ‫SharedStorageSetMethod(): כתיבת צמד מפתח/ערך ל-Shared Storage.
- ‫SharedStorageAppendMethod(): מוסיף ערך למפתח קיים באחסון המשותף, או כותב צמד מפתח/ערך אם המפתח עדיין לא קיים.
- ‫SharedStorageDeleteMethod(): מחיקה של צמד מפתח/ערך מ-Shared Storage.
- ‫SharedStorageClearMethod(): מוחק את כל המפתחות ב-Shared Storage.
```
sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);
```

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

Shared-Storage-Write : set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear

שימוש בכותרות תגובה מבצע batchUpdate() לכל השיטות בכותרת.

קריאה מ-Shared Storage

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

await sharedStorage.get('mykey');

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

מחיקה מ-Shared Storage

אפשר לבצע מחיקות מאחסון משותף באמצעות 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;
```

קריאת קבוצות אינטרס של Protected Audience מתוך האחסון המשותף

אפשר לקרוא את קבוצות האינטרס של Protected Audience מ-worklet של Shared Storage. השיטה interestGroups() מחזירה מערך של אובייקטים מסוג StorageInterestGroup, כולל המאפיינים AuctionInterestGroup ו-GenerateBidInterestGroup.

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

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

המקור של הקשר הגלישה שממנו נטען מודול ה-worklet קובע את המקור של קבוצות הנושאים שנקראות כברירת מחדל. מידע נוסף על מקור ברירת המחדל של ה-worklet ועל האופן שבו משנים אותו מופיע בקטע Executing Shared Storage and Private Aggregation (הפעלת Shared Storage ו-Private Aggregation) במאמר בנושא Shared Storage API.

אפשרויות

כל שיטות השינוי של Shared Storage תומכות באובייקט אפשרויות אופציונלי כארגומנט האחרון.

withLock

האפשרות withLock היא אופציונלית. אם מציינים את האפשרות הזו, השיטה מקבלת נעילה למשאב המוגדר באמצעות Web Locks API לפני שהיא ממשיכה. שם הנעילה מועבר כשמבקשים את הנעילה. השם מייצג משאב שהשימוש בו מתואם בכמה כרטיסיות,עובדים או קוד בתוך המקור.

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

הוגדר
פעולת append
delete
נקה
חבילת עדכונים

אפשר להגדיר את הנעילה באמצעות JavaScript או כותרת תגובה:

שימוש ב-JavaScript

sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });

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

Shared-Storage-Write : set;key="myKey";value="myValue",options;with_lock="myResource"

נעילות של נפח אחסון משותף מחולקות למחיצות לפי מקור הנתונים. הנעילות האלה לא קשורות לנעילות שמתקבלות באמצעות השיטה LockManager, בלי קשר להקשר window או worker. עם זאת, ההיקף שלהם זהה להיקף של נעילות שמתקבלות באמצעות request() בהקשר של SharedStorageWorklet.

בשיטה request() יש אפשרויות שונות להגדרה, אבל נעילות שמתקבלות באחסון משותף תמיד פועלות לפי הגדרות ברירת המחדל הבאות:

‫mode: "exclusive": אי אפשר להחזיק בו-זמנית נעילות אחרות עם אותו שם.
‫steal: false: נעילות קיימות עם אותו שם לא משוחררות כדי לאפשר בקשות אחרות.
‫ifAvailable: false: הבקשות ממתינות לזמן בלתי מוגבל עד שהנעילה תהיה זמינה.

מתי כדאי להשתמש ב-`withLock`

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

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

סדר הנעילות

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

לדוגמה:

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');

דוגמה לשינוי של כמה מפתחות

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

בדוגמה הזו נעשה שימוש בחסימה כדי לוודא שפעולות הקריאה והמחיקה ב-worklet מתבצעות יחד, וכך למנוע הפרעות מחוץ ל-worklet.

בדוגמה הבאה modify-multiple-keys.js מוגדרים ערכים חדשים ל-keyOne ול-keyTwo באמצעות modify-lock ואז מבוצעת הפעולה modify-multiple-keys מתוך ה-worklet:

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

לאחר מכן, בתוך modify-multiple-keys-worklet.js אפשר לבקש את הנעילה באמצעות navigator.locks.request() כדי לקרוא ולשנות את המפתחות לפי הצורך.

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

החלפת הקשר

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

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

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

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

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

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

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

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

Private Aggregation API

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

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

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

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

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

הפעלה של Shared Storage ו-Private Aggregation

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

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

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

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

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

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin: *

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

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

צריך iframe כדי להפעיל את ה-worklet של Shared Storage.

ב-iframe של המודעה, טוענים את מודול ה-worklet באמצעות קריאה ל-addModule(). כדי להריץ את השיטה שרשומה בקובץ ה-worklet‏, sharedStorageWorklet.js, באותו קוד JavaScript של iframe של מודעה, קוראים ל-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);

שימוש בבקשת CORS

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

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

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

מקור נתונים מותאם אישית

כשהערך של dataOrigin מוגדר כמקור תקין, הבעלים של dataOrigin חייב להסכים לעיבוד של Shared Storage עבור אותו dataOrigin על ידי אירוח קובץ JSON שמפרט את המקור של סקריפט ה-worklet בנתיב /.well-known/shared-storage/trusted-origins. הקובץ צריך להיות מערך של אובייקטים עם המפתחות scriptOrigin ו-contextOrigin. הערכים של המפתחות האלה יכולים להיות מחרוזת או מערך של מחרוזות.

יוצרים את הקובץ trusted-origins באמצעות הפרטים הבאים:

ההקשר של המתקשר
מקור וכתובת URL של סקריפט Worklet
מקור הנתונים והבעלים שלו

בטבלה הבאה מוצג אופן ההגדרה של קובץ trusted-origins על סמך המידע הזה:

ההקשר של המתקשר	כתובת URL של סקריפט Worklet	מקור הנתונים	בעלי הנתונים	קובץ JSON של מקורות מהימנים של הבעלים של מקור הנתונים
https://publisher.example	https://publisher.example/script.js	context-origin	https://publisher.example	אין צורך ב-JSON
https://publisher.example	https://ad.example/script.js	script-origin	https://ad.example	אין צורך ב-JSON
https://publisher.example	https://cdn-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": "https://cdn-ad.example", "contextOrigin": "https://publisher.example" }]
כל מתקשר	https://cdn-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": "https://cdn-ad.example", "contextOrigin": "*" }]
https://publisher-a.example, OR https://publisher-b.example	https://cdn-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": "https://cdn-ad.example", "contextOrigin": [ "https://publisher-a.example", "https://publisher-b.example" ] }]
https://publisher.example	https://cdn-a-ad.example/script.js, OR https://cdn-b-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": [ "https://cdn-a-ad.example", "https://cdn-b-ad.example" ], "contextOrigin": "https://publisher.example" }]

לדוגמה, אפשר לארח את קובץ ה-JSON הבא בכתובת https://custom-data-origin.example/.well-known/shared-storage/trusted-origins ולשלב את כל המעבדים המורשים של נתוני Shared Storage למקור https://custom-data-origin.example.

[
  {
    "scriptOrigin": "https://script-origin.a.example",
    "contextOrigin": "https://context-origin.a.example"
  },
  {
    "scriptOrigin": "https://script-origin.b.example",
    "contextOrigin": [
      "https://context-origin.a.example",
      "https://context-origin.b.example"
    ]
}]

השלבים הבאים

בדפים הבאים מוסברים היבטים חשובים של ממשקי ה-API של Shared Storage ושל Private Aggregation.

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

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

אחרי איסוף הדוחות, אפשר לבדוק באמצעות כלי הבדיקה המקומי או להגדיר את סביבת הביצוע המהימנה (TEE) של Aggregation Service כדי לקבל את הדוחות המצטברים.

שיתוף משוב

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

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

Shared Storage API

הפעלת Shared Storage

כתיבה ל-Shared Storage

צירוף ערך

עדכון ערכים בחבילה

קריאה מ-Shared Storage

מחיקה מ-Shared Storage

קריאת קבוצות אינטרס של Protected Audience מתוך האחסון המשותף

אפשרויות

withLock

מתי כדאי להשתמש ב-withLock

סדר הנעילות

דוגמה לשינוי של כמה מפתחות

החלפת הקשר

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

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

Private Aggregation API

הפעלה של Shared Storage ו-Private Aggregation

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

שימוש בבקשת CORS

מקור נתונים מותאם אישית

השלבים הבאים

שיתוף משוב

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

מתי כדאי להשתמש ב-`withLock`