إعداد تقارير المزادات في Protected Audience API

قياس بيانات ونتائج مزاد Protected Audience API

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

لإعداد تقارير عن المقاييس المهمّة التي تجمعها من مزاد إعلانات، تعمل Protected Audience API مع:

• التجميع الخاص الذي يجمع إشارات ونتائج المزادات لإنشاء تقارير موجزة.
• Ads Reporting API لبرامج Fenced Frames وiframes، وهي قناة ضمن الإطارات للتواصل مع وظائف Protected Audience API المصغّرة وتسمح واجهة برمجة التطبيقات بربط البيانات على مستوى الحدث بإشارات مزاد الإعلانات. تُعدّ ميزة إعداد التقارير على مستوى الحدث في Ads Reporting API آلية انتقالية إلى أن يتم تصميم آلية إعداد تقارير أكثر خصوصية.
• تقارير تحديد المصدر التي تسمح لك بربط بيانات الإحالات الناجحة بإشارات المزاد
• مساحة التخزين المشتركة التي تتيح لك كتابة إشارات المزادات إلى مساحة تخزين متعددة المصادر، ثم تسمح لك بالإبلاغ عن تلك البيانات لاحقًا باستخدام ميزة "التجميع الخاص".

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

نظرة عامة على إعداد التقارير في Protected Audience API

سير العمل الإجمالي في Protected Audience

هناك ثلاث فترات زمنية رئيسية يمكن فيها إرسال تقارير إلى خادمك عن البيانات الواردة من مسار مزاد Protected Audience API: وقت المزاد عندما يتم تنفيذ المزاد من الموقع الإلكتروني للناشر، ووقت عرض الإعلان عند عرض الإعلان في إطار مضمّن أو إطار iframe على الموقع الإلكتروني للناشر، ووقت الإحالة الناجحة عندما ينفِّذ المستخدِم إجراءً على موقع إلكتروني آخر يمكن نسبه إلى المزاد.

خلال وقت المزاد، يمكنك إعداد تقارير عن بيانات المزاد باستخدام وظائف صغيرة لإعداد التقارير. أثناء مدة العرض، يمكنك الإبلاغ عن بيانات التفاعل من إطار iframe أو إطار مضمّن مستقل. خلال وقت الإحالة الناجحة، يمكنك إعداد تقارير عن بيانات تحديد المصدر من الصفحة المقصودة باستخدام Attribution Reporting API.

الإبلاغ عن المواقع

وفي مزاد، يمكن للمشترين الإبلاغ عن الإشارات المتوفّرة في وظيفتَي generateBid() وreportWin()، كما يمكن للبائعين الإبلاغ عن الإشارات المتوفّرة في scoreAd() وreportResult(). خارج المزاد، يمكن للمشترين والبائعين الإبلاغ عن البيانات من الإطار الذي عرض الإعلان ومن الموقع الإلكتروني الذي تم إجراء الإحالة الناجحة منه.

الفترة الزمنية	الحساب	الموقع الجغرافي	البيانات متوفرة	تتوفّر واجهة Reporting API
المزاد	مشتري	generateBid()	الإشارات ونتائج المزاد وأداء المزاد	واجهة برمجة التطبيقات الخاصة بالتجميع الخاص
		reportWin()		واجهة برمجة التطبيقات الخاصة للتجميع الخاص Ads Reporting API
	البائع	scoreAd()		واجهة برمجة التطبيقات الخاصة بالتجميع الخاص
		reportResult()		واجهة برمجة التطبيقات الخاصة للتجميع الخاص Ads Reporting API
عرض	المشتري / البائع	وضع إطار على موقع الناشر	البيانات على مستوى الحدث داخل إطار الإعلان	واجهة برمجة التطبيقات الخاصة للتجميع الخاص Ads Reporting API
الإحالة الناجحة	المشتري / البائع	موقع إلكتروني للإحالات الناجحة	البيانات على مستوى الحدث والإحالات الناجحة من موقع الإحالات الناجحة	Attribution Reporting API واجهة برمجة التطبيقات الخاصة بالتجميع الخاص Ads Reporting API

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

البيانات المتوفّرة في مزاد Protected Audience API

تتوفّر البيانات التالية لإعداد تقارير عنها من خلال واجهة برمجة تطبيقات Protected Audience API الصغيرة أثناء المزاد.

الإشارات

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

الإشارة	الوصف	ضبط الموقع الجغرافي	المستخدِمون	البلدان حيث تتوفّر الميزة
auctionSignals	البيانات المتوفرة في سياق مكان إجراء المزاد. يمكن أن تتضمن هذه البيانات معلومات عن محتوى الصفحة وبيانات مستخدمي الطرف الأول وغير ذلك.	يضبطها البائع من خلال الموقع الإلكتروني للناشر في إعدادات المزاد.	المشتري البائع	إنشاء تقرير عرض أسعار الإعلان Win reportResult
directFromSellerSignals	البيانات نفسها لـ "auctionSignals" و"perBuyerSignals" و"sellerSignals"، ولكن يمكن ضمان تلقّيها من البائع المحدّد.	يتم ضبطها من خلال عناوين استجابة HTTP من البائع.	المشتري البائع	إنشاء تقرير عرض أسعار الإعلان Win reportResult
browserSignals	يوفّر المتصفّح بيانات مختلفة (topWindowHostname وinterestGroupOwner وrenderUrl وadComponents وbiddingDurationMsec وIGJoinCount وIGRecency وmodelingSignals).	تم ضبطه من خلال المتصفِّح.	المشتري البائع	إنشاء تقرير عرض أسعار الإعلان Win reportResult
sellerSignals	الإشارات التي يتم تقديمها للبائع لتسجيل نتيجة الإعلان	يضبطها البائع من خلال الموقع الإلكتروني للناشر في إعدادات المزاد.	البائع	نتيجة الإعلان reportWin reportResult
trustedScoringSignals	إشارات في الوقت الفعلي يتم توفيرها للبائع لتسجيل نتيجة الإعلان	يضبط البائع عنوان URL من الموقع الإلكتروني للناشر في إعدادات المزاد.	البائع	نتيجة تقرير أداء الإعلانات
perBuyerSignals	بيانات المزاد السياقية المقدمة إلى مشترين محدّدين. يستطيع البائع استرداد القيم للمشترين قبل بدء المزاد. وهي معرفة المشتري بفرصة الإعلان.	يضبطها البائع من خلال الموقع الإلكتروني للناشر في إعدادات المزاد.	مشتري	إنشاء تقرير عرض أسعار الإعلان Win reportResult
trustedBiddingSignals	إشارات في الوقت الفعلي يتم تقديمها للمشترين من أجل عروض أسعار الإعلانات.	يحدّد المشتري عنوان URL من الموقع الإلكتروني للمعلِن عند ضبط مجموعة الاهتمامات.	مشتري	generateBid
userBiddingSignals	بيانات المستخدم التي قدّمها المشتري.	يتم ضبطها من خلال المشتري من الموقع الإلكتروني للمعلِن عند ضبط مجموعة الاهتمامات .	مشتري	generateBid

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

البيانات المتاحة الأخرى

• بيانات النتائج المتعلّقة ببيانات الفوز والخسارة في المزاد، مثل عرض السعر الفائز وسبب رفض عرض السعر.
• بيانات الأداء التي تحتوي على معلومات وقت الاستجابة، مثل المدّة التي يستغرِقها استرجاع الوظيفة المصغّرة لعروض الأسعار وتنفيذها.

البيانات المتوفّرة خارج مزاد Protected Audience API

خارج مزاد Protected Audience API، تتوفّر فترتان زمنيتان يمكن فيه الإبلاغ عن البيانات.

خلال مدة العرض، عند عرض الإعلان على الموقع الإلكتروني للناشر، يمكن ربط البيانات على مستوى الحدث من داخل إطار iframe أو الإطار السيبراني ببيانات مزادات Protected Audience API وإعداد تقارير عنها إلى خادمك. تتضمن أمثلة البيانات على مستوى الحدث عدد مرات ظهور الإعلان، ونسبة النقر إلى الظهور، والتمرير، وأي أحداث أخرى تقع داخل الإطار.

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

إعداد التقارير على مستوى الحدث

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

إعداد تقارير الفوز بالمزاد على مستوى الحدث باستخدام ميزة "sendReportTo()"

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

على سبيل المثال، يمكن للمشتري الإبلاغ عن مبلغ عرض السعر الفائز من الوظيفة reportWin() لأغراض الفوترة:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

يمكن استخدام الدالة sendReportTo() لإنشاء تقرير الفوز للبائع عند طلبه من reportResult()، وتقرير الفوز للمشتري عند طلبه من reportWin(). إنّ الدالة sendReportTo() متاحة حتى عام 2026 على الأقل،

تقرير التفاعل

يحتوي تقرير التفاعل على بيانات على مستوى الحدث من تصميم إعلان، مثل بيانات مرّات الظهور أو النقرات المرتبطة بإشارات مزاد Protected Audience API التي عرضت الإعلان. نظرًا لعرض الإعلان بعد انتهاء المزاد، لا تكون إشارات المزاد متاحة داخل الإطار الذي يعرض الإعلان. ولربط هذه البيانات من فترات زمنية مختلفة، نوفّر لك آليتَي انتقال لإنشاء تقارير التفاعل.

يمكن استخدام الدالة sendReportTo() الموضّحة أعلاه لربط بيانات المزاد بالبيانات على مستوى الحدث من إطار iframe، ولكنّها لا تعمل مع إطار مضمّن لأنّ المعرّف الفريد لا يمكن تمريره من أداة التضمين لأنّ الاتصال بين أداة التضمين والإطار المحمي محدود. لربط بيانات المزادات بالبيانات على مستوى الحدث من إعلان إطار مضمّن، يمكن استخدام Ads Reporting API.

Ads Reporting API للإطارات المضمّنة وإطارات iframe

توفِّر Ads Reporting API للإطارات المضمّنة وإطارات iframe آلية تتيح لك ربط بيانات المستخدم على مستوى الحدث من إطار إعلان بالإشارات ضمن مزاد شرائح جمهور محمي.

في إحدى الوظائف لإعداد تقارير Protected Audience API، يمكنك تسجيل إشارة إعلان باستخدام وظيفة registerAdBeacon() وتمرير عنوان URL لإعداد التقارير مع الإشارات التي تمّت إضافتها كمَعلمات طلب البحث. عليك أيضًا تحديد الحدث المخصّص الذي تريد ربطه بعنوان URL لإعداد التقارير. وبعد ذلك، في وقت لاحق عند عرض الإعلان في إطار مضمّن، يمكنك تشغيل الحدث المخصّص عن طريق استدعاء الدالة window.fence.reportEvent(). يمكن إضافة البيانات المتوفّرة داخل الإطار الحدودي كحمولة بيانات.

لا تتوفّر الدالة registerAdBeacon() إلا في وظائف إعداد التقارير، ولا تتوفّر في منطق عروض الأسعار للمشتري ومنطق النتائج لدى البائع.

في المثال التالي، يرتبط رقم تعريف الحملة بحمولة على مستوى الحدث مع إحداثيات النقرات:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

ستظلّ Fenced Frames Ads Reporting API متاحة أيضًا حتى عام 2026 على الأقل للأسباب نفسها المتاحة لتحقيق الفوز بالتقارير.

لمزيد من التفاصيل، يمكنك الاطّلاع على الشرح.

الوصول غير المحدود إلى الشبكة

ستتيح الإطارات المضمّنة بين إطارات شبكية تحميل موارد الشبكة بالطريقة نفسها التي يعمل بها إطار iframe، ويمكنك إرسال البيانات على مستوى الحدث داخل الإطارات المضمّنة إلى خادمك. يمكنك إنشاء تقارير على مستوى الحدث من جهة الخادم لاحقًا عن طريق ربط البيانات على مستوى الحدث من إطار مضمّن ببيانات المزاد التي تم إرسالها مع sendReportTo() والتي تمت مناقشتها في قسم آلية إعداد التقارير على مستوى حدث المزاد أعلاه.

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

إنّ آليات إعداد التقارير المتوفّرة على مستوى الحدث المتوفّرة حاليًا في Protected Audience API هي آليات لنقل البيانات، وسيتم تصميم حلّ بديل لإتاحة حالات الاستخدام الحالية بشكل أفضل.

تقرير الإحالة

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

بينما نصمّم حلاً دائمًا أكثر دقة، يمكنك استخدام Ads Reporting API للإطارات المضمّنة كآلية انتقالية لإنشاء تقرير على مستوى الحدث وقابل للتجميع باستخدام Attribution Reporting. تجدر الإشارة إلى أنّ هذه التقارير مخصّصة لقياس الإحالات الناجحة، وهي منفصلة عن تقارير التفاعل على مستوى الحدث والقابلة للتجميع والتي يتم إنشاؤها من المزاد وإطار الإعلان. سننشر شرحًا للحلول الدائمة بشكل أكبر عندما يكون ذلك جاهزًا.

آلية انتقالية

عند تسجيل إشارة إعلان، يمكنك استخدام الكلمة الرئيسية reserved.top_navigation التي ستضيف تلقائيًا عنوان Attribution-Reporting-Eligible لكي يصبح المرشد مؤهّلاً للتسجيل كمصدر تحديد مصدر.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

لإرفاق البيانات على مستوى الحدث بالإشارة التي سجّلتها، يمكنك طلب الرقم setReportEventDataForAutomaticBeacons() من الإطار المحدَّد مع حمولة الأحداث.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

اطّلِع على قسم "تقارير تحديد المصدر" في الشرح التوضيحي لـ Ads Reporting API لمزيد من المعلومات.

مثال على إعداد تقارير التفاعل والإحالات الناجحة

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

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

سير العمل:

1. قبل بدء المزاد، يرسل المشتري معرّفًا فريدًا إلى البائع كجزء من استجابة عروض الأسعار في الوقت الفعلي ("RTB") الآلية. يمكن ضبط المعرّف كمتغيّر مثل auctionId. يتم تمرير رقم التعريف كـ perBuyerSignals في auctionConfig ويصبح متاحًا في وظائف المشتري الصغيرة.
2. وخلال وقت المزاد، يمكن للمشتري تسجيل إشارة إعلان ليتم تشغيلها خلال وقت عرض الإعلان ووقت الإحالة الناجحة (registerAdBeacon()).
   1. لربط إشارات المزاد لحدث إطار إعلان، اضبط auctionId كمعلمة طلب بحث لعنوان URL للإشارة.
   2. لربط إشارات المزاد لحدث إحالة ناجحة، اضبط auctionId في عنوان URL للإشارة.
3. خلال مدة عرض الإعلان، يمكن تشغيل أجهزة المرشد التي سجَّلتها خلال وقت المزاد أو تحسينها باستخدام بيانات على مستوى الحدث.
   1. شغِّل حدث الإطار باستخدام reportEvent()، وانقل البيانات على مستوى الحدث.
   2. إضافة الحمولة على مستوى الحدث إلى إشارة الإحالة باستخدام setReportEventDataForAutomaticBeacons()
   3. سجِّل الإعلان باستخدام Attribution Reporting API من خلال الرد على طلبات إشارة الإعلان باستخدام العنوان Attribution-Reporting-Register-Source.
4. خلال وقت الإحالة الناجحة، يمكنك عرض المصدر الذي سجّلته خلال وقت المزاد.

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

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

تجميع بيانات الجمهور المحمي

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

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

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

تجميع إشارات مزاد الإعلانات

يمكنك تجميع الإشارات المتاحة ضمن الوظائف المصغّرة لخادمك باستخدام ميزة "التجميع الخاص". لتجميع الإشارات، يمكنك استخدام طريقة privateAggregation.contributeToHistogram() المتاحة في الوظيفة المصغّرة لعروض أسعار المشترين، وصفات نتائج البائع، وتقارير المشترين/البائعين.

في هذا المثال، يتمّ تجميع عرض السعر الفائز في حزمة بيانات مالك مجموعة الاهتمامات:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

هذه هي الآلية العامة التي يمكن استخدامها عندما تكون الإشارات التي تريد جمعها غير مرتبطة بالبيانات على مستوى الحدث ولا يبدأها حدث خارج المزاد. لمزيد من المعلومات عن إشارات مزاد الإعلانات لإعداد التقارير، اطّلِع على الشرح.

تجميع إشارات المزاد مع بيانات الأحداث

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

لتجميع إشارات المزاد حسب الأحداث، يمكنك استخدام السمة privateAggregation.contributeToHistogramOnEvent(eventType, contribution) التي تأخذ سلسلة تحدِّد نوع الحدث والمساهمات المطلوب الإبلاغ عنها عند بدء هذا الحدث. يمكنك استدعاء الطريقة مع نوع حدث مخصّص، ثم استدعاء window.fence.reportEvent(eventType) من إطار الإعلان لتشغيل التقرير.

لنفترض أنّك تريد قياس عدد النقرات التي حصل عليها إعلان لإحدى الحملات.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

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

// Ad frame
window.fence.reportEvent('click');

وبعد ذلك، ومن إطار الإعلان لاحقًا، يمكنك بدء عملية إرسال التقرير عن طريق طلب البيانات من reportEvent(eventType):

مزيد من المعلومات عن تفعيل مساهمات التجميع الخاص من إطار من الشرح.

إعداد تقارير عن نتائج المزاد وأدائه

يمكنك أيضًا تجميع نتائج المزادات عند عرضها من خلال حدث فوز أو خسارة بمزاد باستخدام contributeToHistogramOnEvent(eventType, contribution) عند تمرير كلمات رئيسية من نوع حدث محجوز (reserved.win, reserved.loss وreserved.always).

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

عند تقديم قيمة أساسية معيّنة، مثل مبلغ عرض السعر الفائز، يمكنك تحديد مقدار ما تريد إضافته أو طرحه منها، ثم الإبلاغ عن القيمة النهائية. على سبيل المثال، في حال تقديم عرض السعر الفائز بقيمة 5 دولار أمريكي (أو ما يعادله بالعملة المحلية) كقيمة أساسية، يمكنك طرح عرض السعر بقيمة دولارين أمريكيين (أو ما يعادلهما بالعملة المحلية) لحساب القيمة الفعلية البالغة 3 دولار أمريكي (أو ما يعادله بالعملة المحلية) لقيمة الخسارة في المزاد.

إعداد تقارير نتائج المزاد

لنلقِ نظرة على مثال خسرت فيه مزادًا، وتريد معرفة مدى بُعد عرض سعرك عن سعر مقاصة المزاد.

لمعرفة مقدار خسارتك في المزاد، يمكنك طرح سعر عرض السعر من سعر عرض السعر الفائز:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

عند إرسال التقرير، ستكون القيمة الفعلية المبلّغ عنها هي القيمة baseValue المعدّلة والمتغيّرة وفقًا للقيمة offset. لمزيد من المعلومات، يمكنك الاطّلاع على الشرح.

تقارير الأداء

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

يمكنك الاطّلاع على الشرح لمعرفة المزيد.

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

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

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

من إحدى وظائف Protected Audience API المصغّرة، يمكنك كتابة أيّ مفاتيح وقيم في مساحة التخزين المشتركة:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

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

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

لمعرفة مزيد من المعلومات عن مساحة التخزين المشتركة، يُرجى الاطّلاع على قسم "مساحة التخزين المشتركة" في دليل مطوّري التقارير Protected Audience API والشرح والعرض التوضيحي المباشر والرمز التجريبي على GitHub.

ما هي الخطوات التالية؟

نريد المشاركة في محادثات معك للتأكد من أننا ننشئ واجهة برمجة تطبيقات تناسب الجميع.

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

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

إجراء التجارب باستخدام واجهة برمجة التطبيقات

يمكنك تجربة الميزة والمشاركة في محادثة حول Protected Audience API.