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

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

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

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

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

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

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

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

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

المفتاح الذي يتم تقديمه إلى Private Aggregation API هو 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

ملاحظة: على الرغم من تشابه المفاهيم، يتم إنشاء المفتاح بشكل مختلف لواجهة برمجة التطبيقات 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²⁰

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

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

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

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

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

بالنسبة إلى مساحة التخزين المشتركة، يتم تقديم المساهمات خلال 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:

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

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

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

• بالنسبة إلى مساحة التخزين المشتركة: /.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% فقط من القيمة المجمّعة. وبالتالي، فإنّ قيمة 20,000 التي يمكن تجميعها ستتضمّن نسبة إشارة إلى ضجيج أعلى بكثير.

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

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

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

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

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

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

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