أساسيات واجهة برمجة التطبيقات الخاصة بالتجميع الخاص

المفاهيم الرئيسية لواجهة برمجة التطبيقات Private Aggregation API

مَن هو المستهدَف من هذا المستند؟

تتيح Private Aggregation API جمع البيانات المجمّعة من وحدات العمل التي يمكنها الوصول إلى البيانات على جميع المواقع الإلكترونية. إنّ المفاهيم التي تتم مشاركتها هنا مهمة للمطوّرين الذين يبنون وظائف إعداد التقارير ضمن Shared Storage وProtected Audience API.

• إذا كنت مطوّرًا تُنشئ نظام إعداد تقارير لقياس الأداء على مستوى عدّة مواقع
• إذا كنت مسوّقًا أو عالم بيانات أو مستخدِمًا آخر للتقارير التلخيصية ، سيساعدك فهم هذه الآليات في اتخاذ قرارات متعلقة بالتصميم لاسترداد تقرير تلخيصي محسّن.

العبارات الرئيسية

قبل قراءة هذا المستند، من المفيد التعرّف على المفاهيم والمصطلحات الرئيسية. وسيتم وصف كلّ من هذه المصطلحات بالتفصيل هنا.

• مفتاح التجميع (المعروف أيضًا باسم الحزمة) هو مجموعة محدّدة مسبقًا من نقاط البيانات. على سبيل المثال، قد تريد جمع مجموعة من بيانات الموقع الجغرافي حيث يُبلغ المتصفّح عن اسم البلد. قد يحتوي مفتاح التجميع على أكثر من سمة واحدة (على سبيل المثال، البلد ورقم تعريف تطبيق مصغّر للمحتوى).
• القيمة القابلة للتجميع هي نقطة بيانات فردية يتم جمعها في مفتاح تجميع. إذا كنت تريد قياس عدد المستخدِمين من فرنسا الذين شاهدوا المحتوى الخاص بك، تكون France سمة في مفتاح التجميع، وviewCount من 1 هي القيمة القابلة للتجميع.
• يتم إنشاء التقارير القابلة للتجميع وتشفيرها في المتصفّح. بالنسبة إلى Private Aggregation API، يحتوي هذا الحقل على بيانات عن حدث واحد.
• تعالج خدمة التجميع البيانات من التقارير القابلة للتجميع لإنشاء تقرير ملخّص.
• التقرير التلخيصي هو النتيجة النهائية لخدمة التجميع، ويضمّ بيانات مستخدِمين مجمّعة غير مفيدة وبيانات إحالات ناجحة مفصّلة.
• وحدة العمل هي جزء من البنية الأساسية التي تتيح لك تنفيذ دوال JavaScript معيّنة وإرجاع المعلومات إلى المُقدّم. ضمن إحدى وحدات العمل، يمكنك تنفيذ برمجة ‎JavaScript، ولكن لا يمكنك التفاعل مع الصفحة الخارجية أو التواصل معها.

سير عمل "التجميع الخاص"

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

1. عند طلب Private Aggregation API، ينشئ العميل (المتصفّح) ويرسل التقرير القابل للتجميع إلى خادمك ليتم جمعه.
2. يجمع الخادم التقارير من العملاء ويجمّعها لتمت إرسالها إلى "خدمة التجميع".
3. بعد جمع عدد كافٍ من التقارير، ستجمّعها وترسلها إلى خدمة التجميع التي تعمل في بيئة تنفيذ موثوق بها لإنشاء تقرير تلخيصي.

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

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

مفتاح التجميع

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

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

المفتاح الذي يتم تقديمه إلى Private Aggregation API هو BigInt، الذي يتألّف من سمات متعددة. في هذا المثال، السمات هي معرّف التطبيق المصغّر ومعرّف البلد. لنفترض أنّه يمكن أن يتألّف معرّف التطبيق المصغّر من 4 أرقام كحدٍ أقصى، مثل 1234، ويتم ربط كل بلد برقم بترتيب أبجدي، مثل 1 لأفغانستان و61 لفرنسا و195 لزيمبابве. وبالتالي، سيكون المفتاح القابل للتجميع مكوّنًا من 7 أرقام، حيث تكون أول 4 أحرف مخصّصة للمعلَمة WidgetID وتكون آخر 3 أحرف مخصّصة للمعلَمة CountryID.

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

مفتاح التجميع
رقم تعريف التطبيق المصغّر	رقم تعريف البلد
3276	061

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

يمكن أيضًا إنشاء مفتاح التجميع باستخدام آلية تجزئة، مثل SHA-256. على سبيل المثال، يمكن تجزئة السلسلة {"WidgetId":3276,"CountryID":67} ثم تحويلها إلى قيمة BigInt تمثل 42943797454801331377966796057547478208888578253058197330928948081739249096287n. إذا كانت قيمة التجزئة تحتوي على أكثر من 128 بت، يمكنك اقتطاعها لضمان عدم تجاوزها الحد الأقصى المسموح به لقيمة الحزمة الذي يبلغ 2^128−1.

ضمن إحدى وحدات عمل "مساحة التخزين المشتركة"، يمكنك الوصول إلى وحدتَي crypto و TextEncoder التي يمكن أن تساعدك في إنشاء تجزئة. لمزيد من المعلومات حول إنشاء تجزئة، اطّلِع على مقالة SubtleCrypto.digest() على MDN.

يوضّح المثال التالي كيفية إنشاء مفتاح حزمة من قيمة مجزّأة:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

ملاحظة: على الرغم من تشابه المفاهيم، يتم إنشاء المفتاح بشكل مختلف لواجهة برمجة التطبيقات Private Aggregation API مقارنةً بواجهة برمجة التطبيقات Attribution Reporting API. بالنسبة إلى "التجميع الخاص"، يتم تحديد المفتاح الكامل في المرة الواحدة في طلب JavaScript.

قيمة قابلة للتجميع

يتم تجميع القيم القابلة للتجميع لكل مفتاح على مستوى العديد من المستخدِمين لإنشاء إحصاءات ملفّقة في شكل قيم ملخّصة في التقارير الملخّصة.

لنعود الآن إلى مثال السؤال الذي طرحناه سابقًا: "كم عدد المستخدمين الذين شاهدوا تطبيقي المصغّر من فرنسا؟" ستبدو الإجابة عن هذا السؤال على النحو التالي: "تقريباً 4881 مستخدمًا شاهدوا تطبيق مصغّر رقم التعريف 3276 ينحدرون من فرنسا". تكون القيمة القابلة للتجميع 1 لكل مستخدم، و "4881 مستخدم" هي القيمة المجمّعة التي تمثّل مجموع كل القيم القابلة للتجميع لهذا مفتاح التجميع.

مفتاح التجميع		قيمة قابلة للتجميع
رقم تعريف التطبيق المصغّر	رقم تعريف البلد	عدد مرّات المشاهدة
3276	061	1

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

ميزانية المساهمة

يُعرف كل طلب من Private Aggregation API باسم مساهمة. لحماية خصوصية المستخدم، يتم حصر عدد المساهمات التي يمكن جمعها من أحد المستخدمين.

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

يُمثّل ميزانية المساهمات المَعلمة L₁، ويتم ضبطها على 2¹⁶ (65,536) كل عشر دقائق في اليوم مع حدّ أدنى يبلغ 2²⁰ (1,048,576). اطّلِع على الشرح لمزيد من المعلومات عن هذه المَعلمات.

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

لمزيد من المعلومات عن ميزانيات المساهمات، اطّلِع على الشرح. يمكنك أيضًا الرجوع إلى ميزانية المساهمين لمزيد من الإرشادات.

الحد الأقصى للمساهمة لكل تقرير

قد يختلف الحد الأقصى للمساهمة حسب المتصل. في الوقت الحالي، لا يمكن أن تتضمّن التقارير التي يتم إنشاؤها لمُستخدِمي Shared Storage API أكثر من 20 مساهمة لكل تقرير. في المقابل، لا يمكن لمُرسِلي طلبات Protected Audience API إرسال أكثر من 100 مساهمة لكل تقرير. تم اختيار هذه الحدود لموازنة عدد المساهمات التي يمكن تضمينها مع حجم الحمولة.

بالنسبة إلى "مساحة التخزين المشتركة"، يتم تجميع المساهمات التي تم إجراؤها ضمن عملية run() أو selectURL() واحدة في تقرير واحد. بالنسبة إلى "شريحة الجمهور المحمية"، يتم تجميع المساهمات التي يقدّمها مصدر واحد في مزاد معًا.

المساهمات التي تتضمّن مساحة إضافية

تم تعديل المساهمات أيضًا باستخدام ميزة الحشو. إنّ عملية تعبئة الحِزمة تحمي المعلومات عن العدد الفعلي للمساهمات المضمّنة في التقرير القابل للتجميع. تزيد الحشوة الحمولة بمساهمات null (أي بقيمة 0) للوصول إلى طول ثابت.

التقارير القابلة للتجميع

بعد أن يستدعي المستخدم Private Aggregation API، ينشئ المتصفّح تقارير قابلة للتجميع لتعالجها خدمة التجميع في وقت لاحق في الوقت المناسب لإنشاء تقارير summary. يكون التقرير الذي يمكن تجميعه بتنسيق JSON ويحتوي على قائمة مشفّرة بالمساهمات، وكلّ مساهمة هي زوج {aggregation key, aggregatable value}. يتم إرسال التقارير القابلة للتجميع بعد تأخير عشوائي يصل إلى ساعة واحدة.

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

مثال على تقرير قابل للتجميع مع تفعيل وضع debugging:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

يمكن فحص التقارير القابلة للتجميع من صفحة chrome://private-aggregation-internals:

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

جمع التقارير القابلة للتجميع ومعالجتها بشكل مجمّع

يُرسِل المتصفّح التقارير القابلة للتجميع إلى مصدر وحدة العمل التي تحتوي على طلب البيانات من واجهة برمجة التطبيقات Private Aggregation API، وذلك باستخدام المسار المعروف جيدًا التالي:

• بالنسبة إلى مساحة التخزين المشتركة: /.well-known/private-aggregation/report-shared-storage
• بالنسبة إلى "الجمهور المحمي": /.well-known/private-aggregation/report-protected-audience

في نقاط النهاية هذه، ستحتاج إلى تشغيل خادم يعمل كجامع لتلقّي التقارير القابلة للتجميع المُرسَلة من العملاء.

بعد ذلك، من المفترض أن يُجمِّع الخادم التقارير ويرسلها إلى "خدمة التجميع". أنشئ دفعات استنادًا إلى المعلومات المتاحة في الحمولة غير المشفّرة للتقرير القابل للتجميع، مثل حقل shared_info. من الأفضل أن تحتوي الحِزم على 100 تقرير أو أكثر في كل حزمة.

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

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

تتلقّى خدمة التجميع التقارير المشفّرة القابلة للتجميع من أداة الجمع وتُنشئ تقارير summary.

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

التقارير الموجزة

تتيح لك التقارير التلخيصية الاطّلاع على البيانات التي جمعتها مع إضافة ضوضاء إليها. يمكنك طلب تقارير تلخيصية لمجموعة معيّنة من المفاتيح.

يحتوي التقرير التلخيصي على مجموعة من أزواج المفاتيح والقيم بتنسيق قاموس JSON. يحتوي كل زوج على ما يلي:

• ‫bucket: مفتاح التجميع كسلسلة أرقام ثنائية إذا كان مفتاح التجميع المستخدَم هو "123"، يكون الحِزمة "1111011".
• ‫value: القيمة التلخيصية لهدف قياس معيّن، يتمّ جمعها من جميع التقارير القابلة للتجميع المتاحة مع إضافة الضوضاء.

على سبيل المثال:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

الضوضاء والتحجيم

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

يبقى توزيع الضوضاء كما هو بغض النظر عن مجموع كل القيم التي يمكن تجميعها. وبالتالي، كلما زاد عدد القيم التي يمكن تجميعها، قلّ احتمال تأثير الضوضاء.

على سبيل المثال، لنفترض أنّ توزيع الضوضاء له انحراف معيّاري يبلغ 100 ويكون مركزه عند القيمة صفر. إذا كانت قيمة التقرير القابلة للتجميع التي تم جمعها (أو "القيمة القابلة للتجميع") هي 200 فقط، سيكون التباين المعياري للضوضاء هو ‎50% من القيمة المجمّعة. ولكن إذا كانت القيمة القابلة للتجميع هي 20,000، سيكون التباين المعياري للضوضاء ‎0.5% فقط من القيمة المجمّعة. وبالتالي، فإنّ القيمة التي يمكن جمعها والتي تبلغ 20,000 ستعرِض نسبة إشارة إلى ضجيج أعلى بكثير.

لذلك، يمكن أن يساعد ضرب القيمة القابلة للتجميع في عامل تكبير في تقليل الضوضاء. يمثّل عامل التكبير/التصغير مقدار التوسيع الذي تريده لأحد قيم التجميع المحدّدة.

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

لاحتساب عامل تكبير مناسب، قسِّم ميزانية المساهمة على أقصى مجموع للقيم التي يمكن تجميعها في جميع المفاتيح.

يمكنك الاطّلاع على مستندات ميزانية المساهمات لمزيد من المعلومات.

التفاعل مع الملاحظات ومشاركتها

لا تزال واجهة برمجة التطبيقات Private Aggregation API قيد المناقشة وهي خاضعة للتغيير في المستقبل. إذا جرّبت واجهة برمجة التطبيقات هذه ولديك ملاحظات، يسعدنا معرفتها.

• GitHub: يمكنك قراءة الشرح، وطرح الأسئلة والمشاركة في المناقشات. * دعم المطوّرين: يمكنك طرح الأسئلة والانضمام إلى المناقشات في مستودع دعم المطوّرين لمبادرة حماية الخصوصية. * يمكنك الانضمام إلى مجموعة Shared Storage API ومجموعة Protected Audience API للاطّلاع على آخر الأخبار المتعلّقة بميزة "التجميع الخاص".