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

API reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.