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

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

تتمثل الخطة طويلة المدى في السماح للمتصفح بالإبلاغ عن نتائج المزاد بائع ومشتري باستخدام واجهات برمجة تطبيقات التجميع الخاص. كآلية إبلاغ مؤقتة على مستوى الحدث، يتم تنفيذ الرمز يمكن للبائع 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 عند تفعيل جميع واجهات برمجة تطبيقات الخصوصية في عرض الإعلانات ضِمن 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.