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

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

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

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

تجربة العرض التوضيحي

يمكنك تجربة العرض التوضيحي المباشر. اتّبِع الخطوات الواردة في التعليمات الواردة في العرض التوضيحي لتفعيل واجهات برمجة تطبيقات "مبادرة حماية الخصوصية". يساعدك فتح "أدوات مطوري البرامج في Chrome" في الاطّلاع على نتائج حالات الاستخدام المختلفة. حالات الاستخدام المتوفرة في الإصدار التجريبي:

التجميع الخاص
- قياس مدى الوصول الفريد
- قياس الخصائص الديمغرافية
- قياس عدد مرات الظهور باستخدام K+
الاستخدام العام
- قياس حدث التمرير داخل الإطارات المضمّنة
- التنقل في المستوى الأعلى
- التحكّم في الأماكن التي يمكن للجهات الخارجية الكتابة فيها

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

للاطّلاع على البيانات المخزَّنة في "مساحة التخزين المشتركة"، استخدِم "أدوات مطوري البرامج في Chrome". يمكن العثور على البيانات المخزَّنة في "Application -> Shared Storage".

عرض البيانات المخزَّنة في مساحة التخزين المشتركة باستخدام "أدوات مطوري البرامج في Chrome"

عرض تقارير "التجميع الخاص"

للاطّلاع على التقارير المجمّعة التي تم إرسالها، انتقِل إلى chrome://private-aggregation-internals. عندما يكون وضع تصحيح الأخطاء مفعّلاً، يتم إرسال تقرير فورًا (بدون تأخير) إلى [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage، إلى جانب التقرير المتأخر زمنيًا حتى يتم إرساله إلى [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

لتفعيل تصحيح الأخطاء، اتّبِع التعليمات الواردة في القسم تصحيح الأخطاء.

يمكنك الاطّلاع على التقارير في chrome://private-aggregation-internals.

واجهة برمجة تطبيقات مساحة التخزين المشتركة

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

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

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

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

يمكن لتكنولوجيا الإعلانات الكتابة في مساحة التخزين المشتركة باستخدام JavaScript أو عناوين الاستجابة. تحدث القراءة من مساحة التخزين المشتركة فقط داخل بيئة JavaScript معزولة تسمى وظيفة مصغَّرة.

استخدام JavaScript يمكن لتكنولوجيا الإعلانات تنفيذ وظائف محدَّدة لمساحة التخزين المشتركة، مثل ضبط قيم خارج عنصر JavaScript وإلحاقها وحذفها. ومع ذلك، يجب إكمال وظائف مثل قراءة مساحة التخزين المشتركة وإجراء التجميع الخاص من خلال وظيفة JavaScript صغيرة. يمكن العثور على الطرق التي يمكن استخدامها خارج وظيفة JavaScript المصغّرة في صفحة Proposed API Surface - OUT the Worklet.

يمكن العثور على الطرق المستخدمة في الوظيفة الصغيرة أثناء إحدى العمليات من خلال Proposed API Surface - In the Worklet.
استخدام عناوين الاستجابة

أصبحت هذه الميزة متوفرة في الإصدار M119.

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

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

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

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.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: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

تصحيح الأخطاء

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

privateAggregation.enableDebugMode();

لربط التقارير بالسياقات التي أدّت إلى ظهورها، يمكنك ضبط مفتاح تصحيح أخطاء عدد صحيح 64 بت غير موقَّع، ويتم تمريره إلى استدعاء JavaScript. قيمة العمود "debugKey" هي BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

تصحيح أخطاء مساحة التخزين المشتركة

تعرض مساحة التخزين المشتركة رسالة خطأ عامة:

Promise is rejected without and explicit error message

يمكنك تصحيح الأخطاء في مساحة التخزين المشتركة عن طريق إحاطة المكالمات بحظر try-catch.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

تصحيح أخطاء التجميع الخاص

يتم إرسال التقارير إلى /.well-known/private-aggregation/report-shared-storage و/.well-known/private-aggregation/debug/report-shared-storage. تتلقّى تقارير تصحيح الأخطاء حمولة بيانات مشابهة لملف JSON التالي. تُعرِّف هذه الحمولة الحقل api باسم "مساحة تخزين مشتركة".

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

تصحيح أخطاء حمولة البيانات النصية الواضحة

يتم ترميز debug_cleartext_payload بالترميز Base64 CBOR. يمكنك عرض الحزمة والقيمة باستخدام برنامج فك الترميز أو استخدام رمز JavaScript المتوفّر في برنامج فك ترميز مساحة التخزين المشتركة.

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

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

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

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

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

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

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