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

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

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

حالة التنفيذ

ما هي Private Aggregation API؟

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

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

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

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

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

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

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

الاختلافات عن Attribution Reporting

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

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

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

لاختبار واجهة Private Aggregation API محليًا، فعِّل جميع واجهات برمجة التطبيقات المتعلّقة بخصوصية الإعلانات ضِمن chrome://settings/adPrivacy.

مزيد من المعلومات عن الاختبار في التجربة والمشاركة

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

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

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

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

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

باستخدام Shared Storage

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

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

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

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

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

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

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

قياس عدد مرّات الظهور لدى الجمهور بعدد مرّات ظهور أكبر من حدّ معيّن

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

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

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

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

باستخدام Protected Audience API

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

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

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

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

contributeToHistogram()

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

في ما يلي مثال على كيفية استدعائه في Shared Storage لقياس مدى الوصول:

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);

سيؤدي مثال الرمز البرمجي السابق إلى استدعاء Private Aggregation كلّما تم تحميل محتوى 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
  });

لمزيد من المعلومات، يُرجى الاطّلاع على شرح ميزة "إعداد التقارير الموسّعة باستخدام Private Aggregation API".

enableDebugMode()

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

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

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

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

ويمكن استدعاؤها مرة واحدة فقط لكل سياق. وستؤدي أي مكالمات لاحقة إلى حدوث خطأ.

// Enables debug mode
privateAggregation.enableDebugMode();

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

التحقّق من صحة التقرير

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

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

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

Shared Storage

عند استخدام Shared Storage لتنفيذ عملية يمكنها إرسال تقرير قابل للتجميع، يمكنك ضبط معرّف لا يمكن توقّعه خارج التطبيق الصغير.

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

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

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

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

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

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

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

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

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

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

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

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

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