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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مفتاح التجميع
معرّف الأداة	رقم تعريف البلد
3276	061

مثال: في حال توفُّر مساحة مفتاح متوفّرة للبُعد للأرقام المتعددة، ولكن القيمة تحتوي على عدد أقل، أضف أصفارًا بادئة. على سبيل المثال: إذا كان رقم تعريف البلد يسمح بدخول 3 أرقام، يكون رقم تعريف البلد للجزائر 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

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

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

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

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

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

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

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

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

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

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

(1048576). يمكنك الاطّلاع على موضح لمعرفة المزيد عن هذه المعاملات.

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

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

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

بمجرد استدعاء المستخدم لواجهة برمجة تطبيقات التجميع الخاص، ينشئ المتصفح التقارير القابلة للتجميع التي ستتم معالجتها بواسطة خدمة التجميع في وقت لاحق في الوقت المناسب لإنشاء ملخّص التقارير. إنّ التقرير القابل للتجميع بتنسيق 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:

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

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

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

• بالنسبة إلى مساحة التخزين المشتركة: /.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: اطّلِع على موضح، طرح الأسئلة والمشاركة في للمناقشة. * دعم المطوّرين: يمكنك طرح الأسئلة والانضمام إلى المناقشات على دعم مطوّري برامج "مبادرة حماية الخصوصية" المستودع. * الانضمام إلى Shared Storage API مجموعة وProtected Audience API مجموعة للاطّلاع على آخر الإشعارات المتعلّقة بالتجميع الخاص.