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

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

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

حالة التنفيذ

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

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

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

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

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

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

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

اطّلِع على مستند أساسيات Private Aggregation API للتعرّف على مزيد من المعلومات عن المفاهيم الرئيسية المتعلّقة بـ Private Aggregation API.

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

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

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

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

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

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

استخدام العرض التجريبي

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

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

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

‫Private Aggregation هي واجهة برمجة تطبيقات للأغراض العامة لقياس الأداء على جميع المواقع، وهي متاحة للاستخدام في وحدات عمل Shared Storage وProtected Audience API. الخطوة الأولى هي تحديد المعلومات التي تريد جمعها على وجه التحديد. ونقاط البيانات هذه هي أساس مفاتيح التجميع.

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

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

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

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

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

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

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

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

قياس عدد مرّات الظهور للحملات التي تستهدِف أكثر من 1,000 مستخدِم

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

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

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

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

باستخدام Protected Audience API

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

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

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

تتوفّر الدوالّ التالية في عنصر privateAggregation المتاح في وحدات عمل Shared Storage وProtected Audience API.

contributeToHistogram()

يمكنك استدعاء privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })، حيث يكون مفتاح التجميع هو bucket والقيمة القابلة للتجميع هي value. بالنسبة إلى المَعلمة bucket، يجب إدخال BigInt. بالنسبة إلى المَعلمة 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';

    // Don't 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 وحدة العمل، وتستدعي وحدة العمل Private Aggregation API باستخدام معرّف المحتوى الذي تم تحويله إلى مفتاح تجميع (مجموعة).

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

يساعد ضبط رقم تعريف السياق في ضمان دقة البيانات عند المساهمة في النتائج المجمّعة النهائية. ويتم تحقيق ذلك من خلال:

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

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

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

ويتم تضمين هذا المعرّف في التقرير الذي تم إنشاؤه من وحدات العمل. يمكنك تحديده عند استدعاء إحدى طريقتَي التخزين المشترَك run() أو selectURL()، ضمن عنصر الخيارات ضمن المفتاح privateAggregationConfig.

على سبيل المثال:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

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

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

مثال على سير العمل (كما هو موضّح في الرسم البياني أعلاه):

1. يتم تنفيذ عملية "التخزين المشترَك" باستخدام إعداد "التجميع الخاص" لتحديد معرّف سياق وإنشاء تقرير قابل للتجميع.
2. يتم تضمين رقم تعريف السياق في التقرير المجمّع الذي تم إنشاؤه وإرساله إلى الخادم.
3. يجمع الخادم التقارير القابلة للتجميع التي يتم إنشاؤها.
4. تتحقّق العمليات على خادمك من معرّف السياق في كل تقرير قابل للتجميع مقارنةً بمعرّفات السياق المخزّنة لضمان صحته قبل تجميع التقارير وإرسالها إلى خدمة التجميع.

إثبات ملكية رقم تعريف السياق

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

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

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

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

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