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

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

لمن هذا المستند؟

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

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

المصطلحات الرئيسية

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

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

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

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

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

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

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

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

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

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

المفتاح المُقدَّم إلى واجهة برمجة التطبيقات Private Aggregation API هو BigInt، ويتألف من أبعاد متعددة. في هذا المثال، تكون الأبعاد هي معرّف الأداة ومعرّف البلد. لنفترض أنّ رقم تعريف الأداة يمكن أن يصل طوله إلى 4 أرقام، مثل 1234، وتم ربط كل بلد برقم أبجدي، مثلاً أفغانستان 1، وفرنسا 61، وزيمبابوي "195". وبالتالي، يتكوّن المفتاح القابل للتجميع من 7 أرقام، حيث تكون الأحرف الأربعة الأولى محفوظة للرمز 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 اسم مساهمة. ولحماية خصوصية المستخدم، يكون عدد المساهمات التي يمكن جمعها من فرد محدودًا.

عند جمع كل القيم المجمّعة من خلال كل مفاتيح التجميع، يجب أن يكون المجموع أقل من ميزانية المساهمة. يتم تحديد الميزانية على مستوى كل origin على مستوى كل وظيفة، وتكون منفصلة في اليوم لكل من Protected Audience API وقسم "مساحة التخزين المشتركة". تُستخدم فترة تحرك خلال آخر 24 ساعة تقريبًا في اليوم. إذا كان هناك تقرير تجميعي جديد سيتسبب في تجاوز الميزانية، فلن يتم إنشاء التقرير.

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

(1,048,576). اطّلِع على الشرح لمعرفة المزيد من المعلومات عن هذه المَعلمات.

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

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

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

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

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

مثال على تقرير مجمّع مع تفعيل وضع تصحيح الأخطاء:

  "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 تقرير أو أكثر لكل دفعة.

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

خدمة التجميع

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

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

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

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

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

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

مثال:

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

التشويش والضبط

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

ويكون توزيع الضوضاء هو نفسه بغض النظر عن مجموع كل القيم المجمّعة. وبالتالي، كلما ارتفعت القيم المجمّعة، قل تأثير التشويش.

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

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

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

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

يمكنك الاطّلاع على وثائق ميزانية المساهمات لمعرفة المزيد.

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

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

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