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

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

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

Shared Storage API

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

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

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

استدعاء Shared Storage API

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

• استخدام JavaScript: يمكن لتكنولوجيات الإعلان تنفيذ وظائف معيّنة في "مساحة التخزين المشتركة"، مثل ضبط القيم وإلحاقها وحذفها خارج JavaScript worklet. ومع ذلك، يجب إكمال وظائف مثل قراءة Shared Storage وتنفيذ Private Aggregation من خلال worklet في JavaScript. يمكن العثور على الطرق التي يمكن استخدامها خارج JavaScript worklet في Proposed API Surface - Outside the worklet.

  يمكن العثور على الطرق المستخدَمة في Worklet أثناء عملية ما في Proposed API Surface - In the worklet.

• استخدام عناوين الاستجابة

  على غرار 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";
    

يمكنك الاطّلاع على مزيد من المعلومات في Shared Storage: Response Headers.

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

لكتابة البيانات في "مساحة التخزين المشتركة"، استدعِ الدالة 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() إلى إنشاء المفتاح وتحديد القيمة. ويمكن إجراء ذلك باستخدام 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'}
  

  لإضافة محتوى داخل Worklet، اتّبِع الخطوات التالية:

  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

يمكنك القراءة من "مساحة التخزين المشتركة" فقط من داخل worklet.

await sharedStorage.get('mykey');

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

الحذف من Shared Storage

يمكنك تنفيذ عمليات حذف من "مساحة التخزين المشترَكة" باستخدام JavaScript من داخل أو خارج وحدة معالجة العمل أو باستخدام عناوين الاستجابة مع delete(). لحذف جميع المفاتيح في وقت واحد، استخدِم clear() من أي منهما.

• استخدام JavaScript

  لحذف البيانات من Shared Storage من خارج worklet، اتّبِع الخطوات التالية:

  window.sharedStorage.delete('myKey');
  

  لحذف البيانات من "وحدة التخزين المشتركة" من داخل Worklet، اتّبِع الخطوات التالية:

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

يحدّد مصدر سياق التصفّح الذي تم تحميل وحدة العمل منه مصدر المجموعات الاهتمامات التي تتم قراءتها تلقائيًا. لمزيد من المعلومات حول مصدر worklet التلقائي وكيفية تغييره، يُرجى مراجعة قسم "تنفيذ Shared Storage وPrivate Aggregation" في دليل Shared Storage API.

الخيارات

تتيح جميع طرق تعديل Shared Storage استخدام عنصر خيارات اختياري كمعلَمة أخيرة.

withLock

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

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

• محدّدة
• append
• حذف
• محو
• تعديلات مجمَّعة

يمكنك ضبط القفل باستخدام 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

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

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

بعد ذلك، يمكنك طلب القفل باستخدام navigator.locks.request() داخل modify-multiple-keys-worklet.js لقراءة المفاتيح وتعديلها حسب الضرورة.

// 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()، يتم تخزين زوج المفتاح/القيمة في سياق الطرف الأول.

سياق تابع لجهة خارجية

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

Private Aggregation API

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

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

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

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

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

تنفيذ Shared Storage API وPrivate Aggregation API

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

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

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

في إطار iframe الخاص بالإعلان، حمِّل وحدة worklet من خلال استدعاء 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 من مصادر متعددة. عليك ضبط مصدر قسم البيانات الخاص بـ 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();

يجب أن تستجيب نقطة نهاية 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 باستخدام المعلومات التالية:

• سياق المتصل
• مصدر النص البرمجي الخاص بـ Worklet وعنوان 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 وPrivate Aggregation.

• مقدمة عن Shared Storage API (إصدار Chrome للمطوّرين)
• حالات استخدام Shared Storage API (إصدار Chrome للمطوّرين)
• مقدّمة عن Private Aggregation (إصدار Chrome للمطوّرين)
• رسالة توضيحية بشأن Shared Storage API (على GitHub)
• رسالة توضيحية حول Private Aggregation API (GitHub)
• عرض توضيحي حول 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.

• Shared Storage
• التجميع الخاص