نظرة عامة على واجهة برمجة التطبيقات الخاصة لتجميع البيانات

إنشاء تقارير بيانات مجمّعة باستخدام بيانات من Protected Audience وبيانات مواقع إلكترونية متعدّدة من مساحة التخزين المشتركة

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

حالة التنفيذ

الاقتراح الحالة
يمكنك منع تقارير واجهة برمجة التطبيقات الخاصة للتجميع الخاص غير الصالحة من خلال إثبات صحة التقارير لمساحة التخزين المشتركة.
شرح		 متاح في Chrome
يعتمد مدى توفُّر وضع تصحيح أخطاء التجميع الخاص على أهلية الشركات الخارجية.
مشكلة في GitHub		 متوفّرة في Chrome M119
تقليل تأخُّر اكتمال التقرير
شرح		 متوفّرة في Chrome M119
دعم واجهة برمجة التطبيقات Private Aggregation API وخدمة التجميع في Google Cloud
شرح		 متوفّرة في Chrome M121
المساحة المتروكة مع حمولات بيانات التقارير القابلة للتجميع
شرح		 متوفّرة في Chrome M119
يتوفَّر وضع تصحيح أخطاء "التجميع الخاص" لإعداد تقارير "المزاد" لجمع بيانات المشترين
شرح		 متوفر في Chrome M123
إتاحة معرِّفات الفلترة
شرح		 من المتوقع الإطلاق الأولي في Chrome في الربع الثاني من عام 2024.

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

تسمح واجهة برمجة التطبيقات Private Aggregation API للمطوّرين بإنشاء تقارير بيانات مجمّعة باستخدام بيانات من Protected Audience API وبيانات من عدّة مواقع إلكترونية من مساحة التخزين المشتركة.

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

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

المفاهيم الرئيسيّة

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

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

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

الاختلافات عن إعداد تقارير الإحالة

تتشارك واجهة برمجة التطبيقات Private Aggregation API العديد من أوجه التشابه مع Attribution Reporting API. Attribution Reporting هي واجهة برمجة تطبيقات مستقلة مصمّمة لقياس الإحالات الناجحة، في حين أنّ ميزة "التجميع الخاص" مصمّمة للقياسات على مواقع إلكترونية مختلفة بالاقتران مع واجهات برمجة التطبيقات، مثل Protected Audience API و"مساحة التخزين المشتركة". تنتج واجهتا برمجة التطبيقات تقارير مجمّعة تستخدمها الواجهة الخلفية لخدمة التجميع لإنشاء تقارير تلخيصية.

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

اختبار واجهة برمجة التطبيقات هذه

يمكن اختبار واجهة برمجة التطبيقات Private Aggregation API محليًا عن طريق تفعيل علامة تجربة واجهات برمجة التطبيقات لإعلانات "مبادرة حماية الخصوصية" على chrome://flags/#privacy-sandbox-ads-apis.

ضبط تجربة واجهات برمجة التطبيقات لإعلانات "مبادرة حماية الخصوصية" على تفعيل لاستخدام واجهات برمجة التطبيقات هذه
يجب تفعيل تجربة واجهات برمجة التطبيقات لإعلانات "مبادرة حماية الخصوصية" من أجل استخدام واجهات برمجة التطبيقات هذه.

اطّلِع على مزيد من المعلومات عن الاختبار في التجربة والمشاركة.

استخدام العرض التوضيحي

يمكن الوصول إلى الإصدار التجريبي من واجهة برمجة التطبيقات Private Aggregation API for Shared Storage على goo.gle/shared-storage-demo، ويتوفّر الرمز على GitHub. ينفِّذ العرض التوضيحي العمليات من جهة العميل وينتج تقريرًا قابلًا للتجميع يتم إرساله إلى خادمك.

سيتم في المستقبل نشر إصدار تجريبي من واجهة برمجة التطبيقات Private Aggregation API المخصّصة لواجهة Protected Audience API.

حالات الاستخدام

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

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

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

قياس مدى الوصول الفريد

يمكنك قياس عدد المستخدمين الفريدين الذين شاهدوا المحتوى الخاص بهم. يمكن أن توفّر واجهة برمجة التطبيقات الخاصة للتجميع الخاص إجابةً مثل "اطّلع 317 مستخدمًا فرديًا تقريبًا على Content ID 861".

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

قياس الخصائص الديمغرافية

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

يمكن أن توفّر تقنية "التجميع الخاص" إجابة على سبيل المثال: "تتراوح أعمارهم بين 18 و45 عامًا تقريبًا من ألمانيا، 317 مستخدمًا فرديًا تقريبًا". استخدام "مساحة التخزين المشتركة" للوصول إلى بيانات الخصائص الديمغرافية من سياق تابع لجهة خارجية في وقت لاحق، يمكنك إنشاء تقرير باستخدام ميزة "التجميع الخاص" من خلال ترميز سمتَي الفئة العمرية والبلد في مفتاح التجميع.

قياس عدد مرات الظهور باستخدام K+

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

قد يقدّم "التجميع الخاص" إجابةً مثل: "اطّلع 89 مستخدمًا تقريبًا على معرّف Content ID 581 3 مرات على الأقل". يمكن زيادة العدّاد في مساحة التخزين المشتركة من مواقع إلكترونية مختلفة، كما يمكن قراءته داخل وظيفة صغيرة. وعندما يصل العدد إلى K، يمكن إرسال تقرير من خلال "التجميع الخاص".

باستخدام Protected Audience API

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

من إحدى الوظائف المصغّرة في Protected Audience API، يمكنك تجميع بياناتك مباشرةً باستخدام sendHistogramReport() وإعداد تقارير بياناتك استنادًا إلى عامل تشغيل باستخدام reportContributionForEvent()، وهي إضافة خاصة لواجهة Protected Audience API.

الدوال المتاحة

تتوفّر الوظائف التالية في العنصر privateAggregation المتوفّر في وظائف "مساحة التخزين المشتركة" وProtected Audience API.

contributeToHistogram()

يمكنك استدعاء privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })، حيث يكون مفتاح التجميع هو bucket والقيمة القابلة للتجميع مثل value. يجب استخدام BigInt للمَعلمة bucket. يجب إدخال رقم صحيح في معلَمة value.

وفيما يلي مثال على كيفية طلبها في مساحة التخزين المشتركة لقياس مدى الوصول:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

في مثال الرمز أعلاه، سيتم استدعاء "التجميع الخاص" عند تحميل محتوى iframe في المواقع الإلكترونية المختلفة. يُحمِّل رمز iframe العمل المصغَّر، في حين يستدعي العمل المصغَّر واجهة برمجة التطبيقات Private Aggregation API باستخدام Content ID الذي تم تحويله إلى مفتاح تجميع (حزمة).

contributeToHistogramOnEvent()

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

وتستخدِم الطريقة privateAggregation.reportContributionForEvent(eventType, contribution) العنصر eventType الذي يحدّد حدث التشغيل، والعنصر contribution الذي يتم إرساله عند بدء الحدث. يمكن أن يأتي حدث البدء من المزاد نفسه بعد انتهاء المزاد، مثل حدث فوز أو خسارة في المزاد، أو يمكن أن يأتي من إطار مسيَّج عرض الإعلان. لإرسال تقرير عن أحداث المزاد، يمكنك استخدام كلمتَين رئيسيتَين محجوزتَين، reserved.win وreserved.loss وreserved.always. لإرسال تقرير بدأه حدث من إطار مضمّن مستقل، حدِّد نوع حدث مخصّص. لتشغيل الحدث من إطار مضمّن مستقل، استخدِم طريقة fence.reportEvent() المتاحة من Fenced Frames Ads Reporting API.

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

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

يمكنك الاطّلاع على الشرح التوضيحي الموسَّع لإعداد تقارير التجميع الخاص لمزيد من المعلومات.

enableDebugMode()

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

يؤدي استدعاء privateAggregation.enableDebugMode() في الوظيفة إلى تفعيل وضع تصحيح الأخطاء الذي يؤدي إلى تضمين حمولة البيانات غير المشفَّرة (cleartext). يمكنك بعد ذلك معالجة هذه الحمولات باستخدام أداة الاختبار المحلية لخدمة التجميع.

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

يمكنك أيضًا ضبط مفتاح تصحيح الأخطاء عن طريق استدعاء privateAggregation.enableDebugMode({ <debugKey: debugKey> }) حيث يمكن استخدام BigInt كمفتاح لتصحيح الأخطاء. يمكن استخدام مفتاح تصحيح الأخطاء لربط البيانات من القياس المستند إلى ملفات تعريف الارتباط والبيانات من قياس "التجميع الخاص". ويمكن استدعاء هذه الأشياء مرة واحدة فقط لكل سياق. وسيتم تجاهل أي طلبات لاحقة.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

الإبلاغ عن عملية التحقّق

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

هذه الميزة متاحة للاختبار في الإصدار M114 من Chrome والإصدارات الأحدث. لا تتوفّر بعد ميزة التحقّق من التقارير في Protected Audience API.

لمزيد من المعلومات، يمكنك الاطّلاع على الشرح الموجز لإثبات ملكية التقارير.

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

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