إعداد تقارير عن نتائج مزاد 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:

  • تقرير البائع: يُعلم البائع بالفائز في مزاد الإعلانات.
  • تقرير المزايد: يتوفّر للمزايدين الفائزين فقط لإعلامهم بفوزهم في المزاد.

تتمثّل الخطة طويلة الأمد في السماح للمتصفّح بإعداد تقارير عن نتائج المزاد للبائعين والمشترين باستخدام واجهات Private Aggregation API. بصفتها آلية مؤقتة لإعداد التقارير على مستوى الحدث، يمكن للرمز الذي ينفّذ reportResult() للبائع وreportWin() لصاحب عرض السعر الفائز استدعاء الدالة sendReportTo(). يأخذ هذا الحقل وسيطة واحدة: سلسلة تمثّل عنوان 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 عند تفعيل جميع واجهات برمجة التطبيقات Ad Privacy API ضمن chrome://settings/adPrivacy. إذا كنت تستخدم Chrome مع علامات سطر الأوامر لتفعيل Protected Audience API، عليك تفعيل الطرق بشكلٍ صريح من خلال تضمين العلامة BiddingAndScoringDebugReportingAPI. إذا لم يتم تفعيل العلامة، ستظل الطرق متاحة ولكن بدون أي تأثير.

جميع مراجع واجهة Protected Audience API

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

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

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

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

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

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

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

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