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

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

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

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

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

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

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

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

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

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

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

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

البيانات المتاحة ضمن مزاد Protected Audience API

يمكن الإبلاغ عن البيانات التالية من خلال واجهة برمجة تطبيقات Protected Audience API خلال المزاد.

الإشارات

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

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

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

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

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

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

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

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

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

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

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

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

هناك آلية متاحة لإعداد تقارير البيانات على مستوى الحدث داخل مزاد Protected Audience API وهي آلية 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.

في أداة إعداد تقارير 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. على سبيل المثال، قد ينقر أحد المستخدمين على إعلان المنتج الذي تعرضه، ويُعيد توجيهه إلى موقع المعلِن الإلكتروني، ويجري عملية شراء في ذلك الموضع، وتكون مهتمًا بنسب عملية الشراء إلى الإعلان الذي تم عرضه. سيتم دمج 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']
})

اطّلِع على قسم Attribution Reporting في الشرح التوضيحي حول 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.