تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البدء السريع لتنفيذ مساحة التخزين المشتركة والتجميع الخاص
bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

هذا المستند هو دليل بدء سريع لاستخدام "مساحة التخزين المشتركة" و"التجميع الخاص". ستحتاج إلى فهم كلتا أداتَي واجهة برمجة التطبيقات لأنّ "مساحة التخزين المشتركة" تُخزِّن القيم و"التجميع الخاص" ينشئ التقارير القابلة للتجميع.

الجمهور المستهدَف: مزوّدو تقنيات الإعلان وقياس الأداء

Shared Storage API

لمنع التتبُّع في جميع المواقع الإلكترونية، بدأت المتصفّحات بتقسيم جميع أشكال التخزين، بما في ذلك مساحة التخزين على الجهاز وملفات تعريف الارتباط وما إلى ذلك. ولكن هناك حالات استخدام تتطلّب مساحة تخزين غير مقسّمة. توفّر واجهة برمجة التطبيقات Shared Storage API إذن وصول غير محدود للكتابة في مواقع إلكترونية مختلفة من المستوى الأعلى مع إذن قراءة للحفاظ على الخصوصية.

تقتصر مساحة التخزين المشتركة على مصدر السياق (المتصل بالرقم sharedStorage).

تتوفّر مساحة تخزين مشتركة بسعة محدودة لكل مصدر، مع تحديد عدد الأحرف القصوى المسموح بها لكل إدخال. وفي حال بلوغ الحدّ الأقصى، لن يتم تخزين أي إدخالات أخرى. يمكنك الاطّلاع على حدود تخزين البيانات في مقالة الشرح الخاصة بمساحة التخزين المشترَكة.

استدعاء مساحة التخزين المشتركة

يمكن لتقنيات الإعلانات الكتابة في "مساحة التخزين المشتركة" باستخدام JavaScript أو رؤوس الاستجابة. لا تحدث القراءة من "مساحة التخزين المشتركة" إلا ضمن بيئة JavaScript معزولة تُعرف باسم "وحدة عمل".

استخدام JavaScript: يمكن أن تُنفِّذ تقنيات الإعلان وظائف محدّدة لميزة "مساحة التخزين المشتركة"، مثل ضبط القيم وإضافتها وحذفها خارج وحدات JavaScript العملية. ومع ذلك، يجب إكمال وظائف مثل قراءة "مساحة التخزين المشتركة" وتنفيذ "التجميع الخاص" من خلال وحدة عمل JavaScript. يمكن العثور على الطرق التي يمكن استخدامها خارج وحدة JavaScript صغيرة في مساحة عرض واجهة برمجة التطبيقات المقترَحة - خارج الوحدة الصغيرة.

يمكن العثور على الطرق المستخدَمة في "وحدة العمل" أثناء تنفيذ عملية في مساحة عرض واجهة برمجة التطبيقات المقترَحة - في "وحدة العمل".
استخدام رؤوس الاستجابة

على غرار JavaScript، لا يمكن تنفيذ سوى وظائف معيّنة باستخدام رؤوس الاستجابة، مثل ضبط القيم وإضافتها وحذفها في "مساحة التخزين المشتركة". للعمل مع 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";
```

يمكن العثور على مزيد من المعلومات في مقالة مساحة التخزين المشتركة: رؤوس الاستجابة.

الكتابة في مساحة التخزين المشتركة

للكتابة في مساحة التخزين المشتركة، يمكنك استدعاء sharedStorage.set() من داخل ملف معالجة JavaScript أو خارجه. في حال استدعاء الإجراء من خارج وحدة العمل، يتم كتابة البيانات في مصدر سياق التصفّح الذي تم إجراء الاستدعاء منه. في حال استدعاء الإجراء من داخل وحدات العمل، يتم كتابة البيانات في مصدر سياق التصفّح الذي حمّل وحدات العمل. تنتهي صلاحية المفاتيح التي تم ضبطها بعد 30 يومًا من آخر تعديل.

حقل ignoreIfPresent اختياري. إذا كان المفتاح متوفّرًا وتم ضبطه على true، لن يتم تعديله إذا كان متوفّرًا. يتم تجديد تاريخ انتهاء صلاحية المفتاح إلى 30 يومًا من مكالمة set() حتى إذا لم يتم تعديل المفتاح.

إذا تم الوصول إلى "مساحة التخزين المشتركة" عدة مرات في عملية تحميل الصفحة نفسها باستخدام المفتاح نفسه، تتم إعادة الكتابة على قيمة المفتاح. من المستحسن استخدام sharedStorage.append() إذا كان المفتاح بحاجة إلى الاحتفاظ بالقيمة السابقة.

استخدام JavaScript

خارج وحدة العمل:

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-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() من داخل وحدة العمل أو خارجها.

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() من داخل وحدة عمل JavaScript أو خارجها وضبط صفيف منظَّم من الطرق التي تحدّد العمليات المحدّدة. يقبل كلّ مُنشئ طريقة المَعلمات نفسها المستخدَمة في الطريقة الفردية المقابلة له لعمليات الضبط والإضافة والحذف والمحو.

يمكنك ضبط القفل باستخدام JavaScript أو عنوان الاستجابة:

استخدام JavaScript

تشمل طرق JavaScript المتاحة التي يمكن استخدامها مع batchUpdate() ما يلي:
- ‫SharedStorageSetMethod(): لكتابة زوج مفتاح/قيمة في مساحة التخزين المشترَكة
- ‫SharedStorageAppendMethod(): إلحاق قيمة بمفتاح حالي في "مساحة التخزين المشتركة"
- SharedStorageDeleteMethod(): لحذف زوج مفتاح/قيمة من "مساحة التخزين المشتركة"
- SharedStorageClearMethod(): يؤدي هذا الخيار إلى محو جميع المفاتيح في "مساحة التخزين المشتركة".
```
sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);
```

استخدام رؤوس الاستجابة

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

القراءة من مساحة التخزين المشتركة

لا يمكنك القراءة من مساحة التخزين المشتركة إلا من داخل إحدى وحدات العمل.

await sharedStorage.get('mykey');

يحدِّد مصدر سياق التصفّح الذي تم تحميل وحدة العمل من خلاله مساحة التخزين المشتركة التي تتم قراءتها.

الحذف من "مساحة التخزين المشتركة"

يمكنك إجراء عمليات حذف من "مساحة التخزين المشتركة" باستخدام JavaScript من داخل أو خارج الوحدات الصغيرة أو باستخدام رؤوس الاستجابة مع delete(). لحذف كل المفاتيح في آنٍ واحد، استخدِم clear() من أيّ منهما.

استخدام JavaScript

لحذف البيانات من "مساحة التخزين المشتركة" من خارج التطبيق المصغّر:
```
window.sharedStorage.delete('myKey');
```
لحذف البيانات من "مساحة التخزين المشتركة" من داخل القطعة:
```
sharedStorage.delete('myKey');
```
لحذف جميع المفاتيح دفعة واحدة من خارج الوحدات الصغيرة:
```
window.sharedStorage.clear();
```
لحذف جميع المفاتيح دفعة واحدة من داخل القطعة العاملة:
```
sharedStorage.clear();
```
استخدام رؤوس الاستجابة

لحذف القيم باستخدام رؤوس الاستجابة، يمكنك أيضًا استخدام Shared-Storage-Write في عنوان الاستجابة لتمرير المفتاح المراد حذفه.
```
delete;key="myKey"
```
لحذف جميع المفاتيح باستخدام عناوين الاستجابة:
```
clear;
```

قراءة مجموعات الاهتمامات في Protected Audience من مساحة التخزين المشتركة

يمكنك قراءة مجموعات الاهتمامات في Protected Audience من وحدات عمل "مساحة التخزين المشتركة". تعرض الطريقة 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);
}

يحدِّد مصدر سياق التصفّح الذي تم تحميل وحدة العمل منه مصدر مجموعات الاهتمامات التي تتم قراءتها تلقائيًا. للاطّلاع على مزيد من المعلومات عن مصدر "وحدة العمل" التلقائي وكيفية تغييره، راجِع قسم "تنفيذ مساحة التخزين المشتركة والتجميع الخاص" في "الدليل التفصيلي لواجهة برمجة التطبيقات Shared Storage API".

الخيارات

تتوافق جميع طرق تعديل "مساحة التخزين المشتركة" مع عنصر خيارات اختياري كوسيطة أخيرة.

withLock

الخيار withLock اختياري. في حال تحديد هذا الخيار، يوجّه إلى الطريقة الحصول على قفل للمورد المحدّد باستخدام Web Locks API قبل المتابعة. يتم تمرير اسم القفل عند طلب القفل. يمثّل الاسم موردًا يتم تنسيق استخدامه على مستوى علامات تبويب أو عمال أو رموز برمجية متعددة ضمن المصدر.

يمكن استخدام الخيار withLock مع طرق تعديل مساحة التخزين المشتركة التالية:

محدّدة
إلحاق
حذف
محو
تعديلات مجمَّعة

يمكنك ضبط القفل باستخدام JavaScript أو عنوان الاستجابة:

استخدام JavaScript

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

استخدام رؤوس الاستجابة

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

يتم تقسيم أقفال مساحة التخزين المشتركة حسب مصدر البيانات. تكون الأقفال مستقلة عن أي أقفال تم الحصول عليها باستخدام طريقة request()‎ في LockManager، بغض النظر عمّا إذا كانت في سياق window أو worker. ومع ذلك، تشترك هذه الأقفال في النطاق نفسه مع الأقفال التي يتم الحصول عليها باستخدام request() ضمن سياق SharedStorageWorklet.

على الرغم من أنّ طريقة request() تتيح خيارات ضبط مختلفة، تلتزم عمليات القفل التي يتم الحصول عليها ضمن "مساحة التخزين المشتركة" دائمًا بالإعدادات التلقائية التالية:

mode: "exclusive": لا يمكن الحصول على قفل آخر يحمل الاسم نفسه في الوقت نفسه.
steal: false: لا يتم إزالة الأقفال الحالية التي تحمل الاسم نفسه لاستيعاب طلبات أخرى.
ifAvailable: false: تنتظر الطلبات إلى أجل غير مسمى إلى أن يصبح القفل متاحًا.

حالات استخدام `withLock`

تكون الأقفال مفيدة في السيناريوهات التي قد يكون فيها عدّة وحدات عمل يتم تشغيلها في الوقت نفسه (مثلاً، وحدات عمل متعددة في صفحة أو وحدات عمل متعددة في علامات تبويب مختلفة) تبحث كلٌّ منها في البيانات نفسها. في هذا السيناريو، من الأفضل تضمين رمز عمليّة مقترَحة مع قفل لضمان معالجة عمليّة واحدة فقط للتقارير في كلّ مرّة.

هناك حالة أخرى تكون فيها الأقفال مفيدة، وهي إذا كانت هناك مفاتيح متعددة يجب قراءتها معًا في إحدى وحدات العمل، ويجب مزامنة حالتها. في هذه الحالة، يجب لفّ طلبات 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');

مثال على تعديل مفاتيح متعددة

يستخدم هذا المثال قفلًا لضمان تنفيذ عمليتَي القراءة والحذف معًا داخل وحدة العمل، ما يمنع أي تدخل من خارج وحدة العمل.

في المثال التالي على modify-multiple-keys.js، يتمّ ضبط قيم جديدة لـ keyOne وkeyTwo باستخدام modify-lock، ثمّ تنفيذ عملية modify-multiple-keys من القطعة العاملة:

// 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);

تبديل السياق

يتمّ تسجيل بيانات مساحة التخزين المشتركة في المصدر (على سبيل المثال، https://example.adtech.com) لسياق التصفّح الذي نشأ منه الطلب.

عند تحميل الرمز التابع لجهة خارجية باستخدام علامة <script>، يتم تنفيذ الرمز في سياق التصفّح الخاص بالمُضمِّن. لذلك، عندما يُطلِب الرمز البرمجي التابع لجهة خارجية sharedStorage.set()، يتم كتابة البيانات في "مساحة التخزين المشترَكة" للمُضمِّن. عند تحميل الرمز البرمجي التابع لجهة خارجية داخل إطار iframe، يتلقّى الرمز سياق تصفّح جديدًا، ويكون مصدره هو مصدر إطار iframe. وبالتالي، يؤديsharedStorage.set() الطلب الذي يتم إجراؤه من إطار iframe إلى تخزين البيانات في "مساحة التخزين المشتركة" لمصدر إطار iframe.

سياق الطرف الأول

إذا كانت صفحة الطرف الأول تتضمّن رمز JavaScript تابعًا لجهة خارجية يستدعي sharedStorage.set() أو sharedStorage.delete()، يتم تخزين زوج المفتاح/القيمة في سياق الطرف الأول.

البيانات المخزّنة في صفحة الطرف الأول التي تتضمّن JavaScript تابعًا لجهة خارجية

سياق جهة خارجية

يمكن تخزين زوج المفتاح والقيمة في سياق تقنية عرض الإعلانات أو سياق الجهة الخارجية من خلال إنشاء إطار iframe واستدعاء set() أو delete() في رمز JavaScript من داخل إطار iframe.

Private Aggregation API

لقياس البيانات القابلة للتجميع والمخزّنة في "مساحة التخزين المشتركة"، يمكنك استخدام Private Aggregation API.

لإنشاء تقرير، استخدِم دالة contributeToHistogram() داخل وحدة عمل تتضمّن حزمة وقيمة. يتم تمثيل الحزمة بالعدد الصحيح غير الموقَّت الذي يتألّف من 128 بت والذي يجب تمريره إلى الدالة كـ BigInt. يجب أن تكون القيمة عددًا صحيحًا موجبًا.

لحماية الخصوصية، يتم تشفير الحمولة في التقرير، التي تحتوي على الحزمة والقيمة، أثناء نقلها، ولا يمكن فك تشفيرها وتجميعها إلا باستخدام "خدمة التجميع".

سيحدّ المتصفّح أيضًا من المساهمات التي يمكن لموقع إلكتروني تقديمها في طلبات البحث التي تؤدي إلى عرض نتائج. وعلى وجه التحديد، تحدّ ميزانية المساهمة من إجمالي جميع التقارير الواردة من موقع إلكتروني واحد لمتصفّح معيّن في فترة زمنية معيّنة على مستوى جميع الحِزم. في حال تجاوز الميزانية الحالية، لن يتم إنشاء تقرير.

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

تنفيذ "مساحة التخزين المشتركة" و"التجميع الخاص"

بشكلٍ تلقائي، عند استخدام مساحة تخزين مشترَكة مع createWorklet()، سيكون مصدر قسم البيانات هو مصدر سياق التصفّح الذي يتمّ استخدامه في الاستدعاء، وليس مصدر نصّ برمجيّ "وحدة العمل" نفسه.

لتغيير السلوك التلقائي، اضبط السمة dataOrigin عند الاتصال createWorklet.

dataOrigin: "context-origin": (تلقائي) يتم تخزين البيانات في مساحة التخزين المشترَكة لمكان عرض سياق التصفّح الذي يتمّ استدعاؤه.
dataOrigin: "script-origin": يتم تخزين البيانات في مساحة التخزين المشتركة لمصدر نص برمجي للوحدة الصغيرة. يجب الموافقة على تفعيل هذا الوضع.
dataOrigin: "https://custom-data-origin.example": يتم تخزين البيانات في مساحة التخزين المشتركة لمصدر بيانات مخصّص. يجب تفعيل هذا الوضع والحصول على موافقة من مالك مصدر البيانات المخصّصة، كما هو موضّح بالتفصيل في مصدر البيانات المخصّصة.

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

للموافقة على الميزة، يجب أن تستجيب نقطة نهاية النص البرمجي باستخدام العنوان Shared-Storage-Cross-Origin-Worklet-Allowed عند استخدام "script-origin" أو مصدر مخصّص. بالنسبة إلى الطلبات من مصادر متعددة، يجب أيضًا تفعيل CORS.

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

يمكنك أيضًا تشغيل نصوص برمجية من مصادر متعددة باستخدام إطار iframe تابع لجهة خارجية، وفي هذه الحالة ستكون إجراءات مساحة التخزين المشتركة في سياق التصفّح التابع لجهة خارجية.

استخدام إطار iframe من مصدر مختلف

يجب استخدام إطار iframe لاستدعاء وحدة التخزين المشتركة.

في إطار iframe للإعلان، حمِّل وحدة العمل المصغّر من خلال استدعاء addModule(). لتنفيذ الطريقة المسجّلة في ملف sharedStorageWorklet.js worklet، استخدِم sharedStorage.run() في ملف JavaScript لإطار iframe الإعلاني نفسه.

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

في نصّ "وحدة العمل"، عليك إنشاء فئة باستخدام 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);

استخدام طلب من مصدر خارجي

تسمح ميزة "مساحة التخزين المشتركة" و"التجميع الخاص" بإنشاء وحدات عمل من مصادر متعددة بدون الحاجة إلى استخدام إطارات iframe من مصادر متعددة.

يمكن لصفحة الطرف الأول أيضًا طلب createWorklet() إلى نقطة نهاية لغة JavaScript التي تعود لمصدر مختلف. عليك ضبط مصدر تقسيم البيانات للوحدة النمطية لتكون مصدر النص البرمجي عند إنشاء الوحدة النمطية.

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

يجب أن تستجيب نقطة نهاية JavaScript المشتركة المنشأ بالرؤوس التالية: Shared-Storage-Cross-Origin-Worklet-Allowed ويُرجى العلم أنّه تم تفعيل بروتوكول مشاركة الموارد المشتركة المنشأ (CORS) لمعالجة الطلب.

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

ستتضمّن وحدات العمل التي تم إنشاؤها باستخدام createWorklet() selectURL وrun(). لا يتوفّر addModule() لإجراء ذلك.

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

مصدر البيانات المخصّصة

عند ضبط dataOrigin على مصدر صالح، على مالك dataOrigin الموافقة على معالجة "مساحة التخزين المشتركة" لهذا dataOrigin من خلال استضافة ملف JSON يسرد مصدر نص برمجي "وحدة العمل" في المسار /.well-known/shared-storage/trusted-origins. يجب أن يكون الملف مصفوفة من العناصر التي تحتوي على المفتاحَين scriptOrigin وcontextOrigin. يمكن أن تكون قيم هذه المفاتيح سلسلة أو مصفوفة من السلاسل.

أنشئ ملف trusted-origins باستخدام المعلومات التالية:

سياق المتصل
مصدر نص "وحدة العمل" وعنوان URL
مصدر البيانات ومالكها

يوضّح الجدول التالي كيفية إنشاء ملف trusted-origins استنادًا إلى هذه المعلومات:

سياق المتصل	عنوان URL للنص البرمجي لوحدة العمل	مصدر البيانات	مالك البيانات	ملف 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، أو 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، أو 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 ودمج جميع المعالجات المسموح بها لبيانات "مساحة التخزين المشتركة" لمصدر 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"
    ]
}]

الخطوات التالية

توضِّح الصفحات التالية الجوانب المهمة لواجهات برمجة التطبيقات Shared Storage وPrivate Aggregation.

بعد التعرّف على واجهات برمجة التطبيقات، يمكنك بدء جمع التقارير، التي يتم إرسالها كطلب POST إلى نقاط النهاية التالية بتنسيق JSON في نص الطلب.

تقارير تصحيح الأخطاء: context-origin/.well-known/private-aggregation/debug/report-shared-storage
التقارير - context-origin/.well-known/private-aggregation/report-shared-storage

بعد جمع التقارير، يمكنك اختبارها باستخدام أداة الاختبار المحلي أو إعداد بيئة التنفيذ الموثوق بها للخدمة للحصول على التقارير المجمّعة.

مشاركة ملاحظاتك

يمكنك مشاركة ملاحظاتك حول واجهات برمجة التطبيقات والمستندات على GitHub.

البدء السريع لتنفيذ مساحة التخزين المشتركة والتجميع الخاص bookmark_borderbookmark تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

Shared Storage API

استدعاء مساحة التخزين المشتركة

الكتابة في مساحة التخزين المشتركة

إلحاق قيمة

تعديل القيم بشكل مجمّع

القراءة من مساحة التخزين المشتركة

الحذف من "مساحة التخزين المشتركة"

قراءة مجموعات الاهتمامات في Protected Audience من مساحة التخزين المشتركة

الخيارات

withLock

حالات استخدام withLock

ترتيب الأقفال

مثال على تعديل مفاتيح متعددة

تبديل السياق

سياق الطرف الأول

سياق جهة خارجية

Private Aggregation API

تنفيذ "مساحة التخزين المشتركة" و"التجميع الخاص"

استخدام إطار iframe من مصدر مختلف

استخدام طلب من مصدر خارجي

مصدر البيانات المخصّصة

الخطوات التالية

مشاركة ملاحظاتك

البدء السريع لتنفيذ مساحة التخزين المشتركة والتجميع الخاص
bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

حالات استخدام `withLock`