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

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

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

حالة التنفيذ

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

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

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

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

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

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

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

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

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

الاختلافات عن تقارير تحديد المصدر

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

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

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

لاختبار واجهة برمجة التطبيقات Private Aggregation API على الجهاز، يجب تفعيل جميع واجهات برمجة التطبيقات Ad Privacy API ضمن chrome://settings/adPrivacy.

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

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

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

سيتم في المستقبل نشر عرض توضيحي لواجهة Private Aggregation API الخاصة بواجهة Protected Audience API.

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

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

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

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

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

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

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

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

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

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

قياس التردد K+

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

يمكن أن توفّر ميزة "تجميع خاص" إجابة مثل "شاهد 89 مستخدمًا تقريبًا نظام Content ID 581 ثلاث مرات على الأقل". يمكن زيادة العدّاد في مساحة التخزين المشتركة من مواقع مختلفة ويمكن قراءته في وظيفة صغيرة. عند وصول العدد إلى 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 على تحميل الوظيفة المصغّرة، وتستدعي الوظيفة المصغّرة واجهة برمجة تطبيقات التجميع الخاص مع تحويل 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() في الوظيفة المصغّرة إلى تفعيل وضع تصحيح الأخطاء الذي يجعل التقارير القابلة للتجميع تتضمّن حمولة البيانات غير المشفَّرة (النص الواضح). يمكنك بعد ذلك معالجة هذه الحمولات باستخدام أداة الاختبار المحلي في خدمة التجميع.

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

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

ويمكن استدعاء هذه مرة واحدة فقط لكل سياق. ستعرض أي استدعاءات لاحقة استثناءً.

// Enables debug mode
privateAggregation.enableDebugMode();

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

إثبات صحة الإبلاغ

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

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

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

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

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