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

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

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

Shared Storage API

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

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

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

استدعاء Shared Storage

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

• استخدام JavaScript: يمكن أن تُنفِّذ تقنيات الإعلان وظائف محدّدة لميزة "مساحة التخزين المشتركة"، مثل ضبط القيم وإضافتها وحذفها خارج وحدات معالجة JavaScript التابعة للتطبيق. ومع ذلك، يجب إكمال دوالّ مثل قراءة Shared Storage وتنفيذ Private Aggregation من خلال وحدة عمل 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 أو خارجها وضبط صفيف منظَّم من الطرق التي تحدّد العمليات المحدّدة. يقبل كلّ مُنشئ طريقة المَعلمات نفسها المُستخدَمة في الطريقة الفردية المقابلة للإعداد والتضمين والحذف والمحو.

يمكنك استدعاء batchUpdate() من 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 : set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear
  

يؤدي استخدام عناوين الاستجابة إلى تنفيذ batchUpdate() لجميع الطرق الواردة في العنوان.

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

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

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",options;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');

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

يضمن خيار withLock مع batchUpdate() الاستبعاد المتبادل مع العمليات المتزامنة الأخرى التي تحصل على القفل نفسه. لا يمكنك تطبيق خيار withLock لـ batchUpdate() إلا على الحزمة بأكملها. يؤدي تطبيق withLock على أي عنصر طريقة فردي ضمن الحزمة إلى حدوث استثناء.

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

يحدِّد مثال 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);

تبديل السياق

يتمّ تسجيل بيانات Shared Storage في المصدر (مثل https://example.adtech.com) لسياق التصفّح الذي نشأ منه الطلب.

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

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

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

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

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

Private Aggregation API

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

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

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

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

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

تنفيذ Shared Storage وPrivate Aggregation

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

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

• dataOrigin: "context-origin": (الإعداد التلقائي) يتم تخزين البيانات في مساحة التخزين المشترَكة لمكان ظهور سياق التصفّح الذي يتمّ استدعاؤه.
• dataOrigin: "script-origin": يتم تخزين البيانات في مساحة التخزين المشتركة لمصدر نص برمجي للوحدة الصغيرة. يجب الموافقة على تفعيل هذا الوضع.
• 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 تابع لجهة خارجية، وفي هذه الحالة ستكون إجراءات مساحة التخزين المشتركة في سياق التصفّح التابع لجهة خارجية.

استخدام إطار 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 استنادًا إلى هذه المعلومات:

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.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 API وPrivate Aggregation API.

• مقدّمة عن مساحة التخزين المشتركة (إصدار Chrome للمطوّرين)
• حالات استخدام مساحة التخزين المشتركة (إصدار Chrome للمطوّرين)
• مقدّمة عن ميزة "التجميع الخاص" (إصدار Chrome للمطوّرين)
• شرح Shared Storage (GitHub)
• شرح عملية التجميع الخاصة (GitHub)
• العرض التجريبي لميزتَي "مساحة التخزين المشتركة" و"التجميع الخاص"

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

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

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

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

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

• مساحة التخزين المشتركة
• التجميع الخاص