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

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

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

حالة التنفيذ

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

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

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

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

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