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

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

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

حالة التنفيذ

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

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

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

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

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

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

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

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

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

تشترك واجهة برمجة التطبيقات 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، يمكن إرسال تقرير من خلال تجميع خاص.

تحديد المصدر بالاستناد إلى نقاط اتصال متعددة

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

باستخدام 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 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 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) });

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

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

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

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

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

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