دليل البائع: تنفيذ مزادات الإعلانات

دليل Seller API ومراجع لمزاد الإعلانات في Protected Audience API

تتضمّن هذه المقالة مرجعًا فنيًا لمزاد الإعلانات، كما هو موضّح في التكرار الحالي لواجهة Protected Audience API التجريبية.

الاطّلاع على دليل المطوِّر مدى الحياة أو Protected Audience API، ويمكنك الاطّلاع على الفيديو التوضيحي حول Protected Audience API للحصول على مناقشة مفصّلة حول كيفية إجراء البائعين للمزادات على الجهاز فقط

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

ما هو مزاد الإعلانات في Protected Audience API؟

مزاد الإعلانات في Protected Audience API هو مجموعة من برامج JavaScript الصغيرة يتم تشغيل المتصفّح على جهاز المستخدم لاختيار إعلان للحفاظ على الخصوصية، سيتم عرض كل الإعلانات رمز المزاد من البائع والمشترين يتمّ تشغيله في لغة JavaScript معزولة المهام الدراسية التي لا يمكنها التحدث إلى العالم الخارجي.

ست مراحل في مزاد إعلانات Protected Audience API
يوضّح هذا المخطّط البياني كل مرحلة من مراحل مزاد الإعلانات في Protected Audience API.
  1. يزور أحد المستخدِمين موقعًا إلكترونيًا يعرض الإعلانات.
  2. ينفذ رمز البائع navigator.runAdAuction(). يحدد هذا أي المساحة الإعلانية للبيع ومن يمكنه تقديم عروض أسعار. يجب أن يتضمن البائعون أيضًا نصًا برمجيًا التي تحقق كل عرض سعر، scoreAd().
  3. يتم تنفيذ رمز المشتري الذي تمت دعوته لإنشاء عرض سعر، وعنوان URL لإعلان ذي صلة. والمواد الإبداعية وغيرها من البيانات. يستطيع النص البرمجي لعرض الأسعار الاستعلام عن البيانات في الوقت الفعلي مثل ميزانية الحملة الإعلانية المتبقية من ميزانية المشتري خدمة المفتاح/القيمة.
  4. يسجِّل رمز البائع كل عرض سعر ويختار فائزًا. يستخدم هذا المنطق دالة قيمة عرض السعر والبيانات الأخرى تؤدي إلى تحقيق مدى الرغبة في عرض السعر. إعلانات لا يمكن تفوقها رفض الفائز بحسب المحتوى. يمكن للبائع استخدام ملفات تعريف الارتباط الخاصة به خدمة المفتاح/القيمة للبيانات في الوقت الفعلي.
  5. ويتم عرض الإعلان الفائز كقيمة مبهمة يتم عرضها في إطار مضمّن. كل من البائع لن يتمكّن الناشر من الاطّلاع على هذه القيمة.
  6. ويتم إبلاغ البائع والمشترين الفائزين عن المزاد.

متى يُجرى المزاد؟

يمكن إدارة Protected Audience API بشكل فردي أو من خلال المزادات الآلية. في حال أراد بائعون متعددون المزاد الآلي:

  1. يزور المستخدم موقعًا إلكترونيًا مشاركًا.
  2. يجري بائع آخر مزادًا آليًا للعثور على إعلان سياقي لشريحة إعلانية متاحة.
  3. يتمّ إجراء مزاد Protected Audience API.
  4. يقارن scoreAd() عروض أسعار المشتري بنتائج المزاد الأول.

ويتم رفض عروض الأسعار التي لا يمكنها تجاوز الفائز المستند إلى المحتوى.

مَن يدير مزاد الإعلانات في Protected Audience API؟

هناك جهات متعددة يمكن أن تُجري مزادًا لبيع مساحة إعلانية.

على سبيل المثال:

  • ناشر محتوى: يعمل بنفسه لاستضافة محتوى الإعلان على موقعه الإلكتروني.
  • منصّة جهة العرض (SSP): العمل مع الناشر وتقديم خدمات أخرى.
  • النص البرمجي التابع لجهة خارجية: العمل لدى الناشر من أجل تفعيل المشاركة في مزادات الإعلانات.

باستخدام Protected Audience API، تتوفّر للبائع ثلاث مهام:

  • فرض قواعد الناشرين: تحديد المشترين وعروض الأسعار المؤهلة.
  • تنفيذ منطق المزاد: تشغيل JavaScript في worklets لحساب نقاط الرغبة لكل عرض أسعار.
  • أبلِغ عن نتيجة المزاد.

يتم تنفيذ هذه المهام آليًا، وذلك من خلال الرمز الذي يوفره البائع عند بدء مزاد إعلانات من خلال استدعاء وظيفة JavaScript navigator.runAdAuction()

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

runAdAuction()

يرسل البائع طلبًا إلى متصفح المستخدم لبدء مزاد إعلانات من خلال الاتصال بالرقم navigator.runAdAuction().

على سبيل المثال:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

تعرض الدالة runAdAuction() تعهدًا يتم حله إلى URN (urn:uuid:<something>) الذي يمثّل نتائج مزاد الإعلانات. ولا يمكن للمتصفّح فك ترميز ذلك إلا عند تمريره إلى إطار محاط بسياج للعرض: لا يمكن لصفحة الناشر فحص الإعلان الفائز.

يراعي النص البرمجي decisionLogicUrl كل إعلان على حدة، إلى جانب وعرض السعر والبيانات الوصفية، واحد تلو الآخر، ثم تعين له درجة الرغبة.

auctionConfig مكانًا للإقامة

seller
مطلوب
مثال: 'https://ssp.example'
الدور: أصل البائع.
decisionLogicUrl
مطلوب
مثال: 'https://ssp.example/auction-decision-logic.js'
الدور: عنوان URL لوظيفة JavaScript الخاصة بالمزاد.
trustedScoringSignalsUrl
اختيارية
مثال: 'https://ssp.example/scoring-signals'
الدور: عنوان URL لخادم البائع الموثوق به.
interestGroupBuyers
مطلوب
مثال: ['https://dsp.example', 'https://buyer2.example', ...]
الدور: طلب من جميع مالكي مجموعات الاهتمامات تقديم عروض أسعار في المزاد.
ملاحظات: يجوز للبائع تحديد interestGroupBuyers: للسماح لجميع مجموعات المصالح بتقديم عروض أسعار. وبعد ذلك، يتم قبول الإعلانات أو رفضها استنادًا إلى معايير أخرى غير إدراج مالك مجموعة الاهتمامات. على سبيل المثال، يجوز للبائع مراجعة تصاميم الإعلانات للتأكّد من التزامها بسياساته.
auctionSignals
اختيارية
مثال: {...}
الدور: معلومات البائع حول سياق الصفحة ونوع المزاد وما إلى ذلك
sellerSignals
اختيارية
مثال: {...}
الدور: معلومات تستند إلى إعدادات الناشر، وتقدّم طلب إعلان سياقيًا، وما إلى ذلك.
sellerTimeout
اختيارية
مثال: 100
الدور: الحد الأقصى لوقت تشغيل النص البرمجي scoreAd() للبائع (بالمللي ثانية).
perBuyerSignals
اختيارية
مثال: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
الدور: إشارات سياقية من الخادم لكل مشترٍ محدَّد عن الصفحة.
perBuyerTimeouts
اختيارية
مثال: 50
الدور: الحد الأقصى لوقت تشغيل النصوص البرمجية generateBid() لمشترٍ معيّن.
componentAuctions
اختيارية
مثال: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
الدور: عمليات ضبط إضافية لمزادات المكوّنات

decisionLogicUrl

decisionLogicUrl هي سمة لكائن المزاد، تم تمريره إلى runAdAuction(). يجب أن يتضمن عنوان URL هذا نصًا برمجيًا scoreAd(). يتم تشغيل هذا المنطق مرة واحدة لكل إعلان لتحديد رغبته.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals هو كائن تم إنشاؤه من خلال المتصفّح، ويتضمّن معلومات. يعرفها المتصفح وكذلك النص البرمجي للمزاد الخاص بالبائع قد يرغب في التحقق:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

وقبل بدء المزاد، يجد البائع أفضل إعلان سياقي الشريحة الإعلانية المتوفرة حاليًا جزء من منطق scoreAd() يرفض أي إعلان لا يمكن عرضه الفوز على التطبيقات الفائزة من حيث المحتوى.

scoreAd()

تستخدم scoreAd() الوسيطات التالية:

الوسيطة الدور
adMetadata البيانات الوصفية العشوائية التي يقدّمها المشتري
auctionConfig تم تمرير كائن إعدادات المزاد إلى navigator.runAdAuction().
bid قيمة عرض سعر رقمية.
trustedScoringSignals القيم التي تمّ استردادها في وقت المزاد من الخادم الموثوق به للبائع، والتي تمثّل رأي البائع في الإعلان

الأسئلة الشائعة

كيف يتم تحديد الفائز في المزاد ومن يختاره؟

ويوفر البائع منطق النتائج لتحديد درجة الرغبة لكل إعلان، ويختار المتصفح أعلى نتيجة كالإعلان الفائز.

يضمِّن البائع أسلوبًا منطقيًا في الدالة scoreAd()، وينفّذ المتصفّح الوظيفة في ملف صغير يتضمّن اتصالاً محدودًا برمز خارجه. ولا يعرض المتصفح نفسه الإعلانات. ويكون المتصفح مسؤولاً بشكل حصري عن تنفيذ منطق النتائج واختيار عرض السعر الذي حقق أعلى نتيجة.

كل مراجع Protected Audience API

以下是 API 参考指南：

Protected Audience API 说明信息还详细介绍了功能支持和限制条件。