تمت ترجمة هذه الصفحة بواسطة Cloud Translation 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"
```

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

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

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;
```

تبديل السياق

يتمّ تسجيل بيانات "مساحة التخزين المشتركة" في المصدر (على سبيل المثال، 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

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

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

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

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

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

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

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

لتغيير السلوك التلقائي، اضبط السمة 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

استخدام إطار 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
    });
  }
}

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

توضِّح الصفحات التالية الجوانب المهمة لواجهات برمجة التطبيقات 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.