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

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

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

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

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

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

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

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

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