إعداد تقارير عن نتائج مزاد Protected Audience API

دليل البائعين والمشترين لإنشاء تقارير مزادات Protected Audience API

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

اقرأ دليل المطوِّر للاطّلاع على دورة حياة Protected Audience API الكاملة، وراجِع المعلومات التوضيحية في Protected Audience API للحصول على مناقشة مفصّلة حول إعداد التقارير على مستوى الحدث (المؤقت).

ألست مطوّرًا؟ يُرجى الرجوع إلى نظرة عامة على Protected Audience API.

ماذا يتضمّن تقرير Protected Audience API؟

يتوفّر تقريران متوفّران في Protected Audience API:

  • تقرير البائع: تُبلغ البائع بالفائز في مزاد الإعلانات.
  • تقرير المشترين: يتوفر هذا التقرير للمشترين الفائزين فقط، لمعرفة أنهم قد فازوا في المزاد.

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

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

البائع: reportResult()

يمكن أن تتضمن لغة JavaScript للبائع المتوفرة في decisionLogicUrl (والذي يوفر أيضًا scoreAd()) وظيفة reportResult()، للإبلاغ عن نتيجة المزاد.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

الوسائط التي تم تمريرها إلى هذه الدالة هي:

auctionConfig

تم تمرير عنصر إعداد المزاد إلى navigator.runAdAuction().

browserSignals

كائن يتم إنشاؤه بواسطة المتصفح الذي يوفر معلومات عن المزاد. مثال:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

ويتم استخدام القيمة المعروضة لهذه الدالة كوسيطة sellerSignals لدالة reportWin() لمقدّم عرض الأسعار الفائز.

المشتري: reportWin()

ويمكن أن تتضمّن JavaScript الخاص بمقدِّم عرض السعر الفائز (والذي قدّم generateBid() أيضًا) دالة reportWin() للإبلاغ عن نتيجة المزاد.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

الوسائط التي تم تمريرها إلى هذه الدالة هي:

auctionSignals وperBuyerSignals

تم تمرير القيم نفسها إلى generateBid() لعرض السعر الفائز.

sellerSignals

تمثّل القيمة المعروضة reportResult()، والتي تمنح البائع فرصة لنقل المعلومات إلى المشتري.

browserSignals

كائن يتم إنشاؤه بواسطة المتصفح الذي يوفر معلومات عن المزاد. مثال:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

تنفيذ إعداد التقارير المؤقتة

تتوفّر طريقتان متاحتان مؤقتًا في Chrome لإعداد تقارير المزادات:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

تأخذ كل طريقة من هذه الطرق وسيطة واحدة: عنوان URL يتم جلبه بعد اكتمال المزاد. ويمكن استدعاؤها عدة مرات في كل من scoreAd() وgenerateBid() باستخدام وسيطات عناوين URL مختلفة.

يرسل متصفِّح Chrome تقارير عن الأخطاء وفقدان الأخطاء فقط عند اكتمال المزاد. إذا تم إلغاء مزاد (على سبيل المثال، بسبب التنقل الجديد)، فلن يتم إنشاء أي تقارير.

تتوفّر هاتان الطريقتان تلقائيًا في Chrome في حال تفعيل chrome://flags/#privacy-sandbox-ads-apis. في حال تشغيل Chrome باستخدام علامات سطر الأوامر لتفعيل Protected Audience API، عليك تفعيل الطرق بشكل صريح من خلال تضمين العلامة BiddingAndScoringDebugReportingAPI. إذا لم يتم تمكين العلامة، فستبقى الطرق متاحة ولكن بدون اتخاذ أي إجراء.

كل مراجع Protected Audience API

تتوفر الأدلة المرجعية لواجهة برمجة التطبيقات:

يوفّر الشرح في Protected Audience API أيضًا تفاصيل حول إتاحة الميزات والقيود المفروضة عليها.

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

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

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

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

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

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