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

دليل ومراجع 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 في دورات تدريبية لاحتساب نتيجة الرغبة لكل عرض سعر.
  • أبلِغ عن نتائج المزاد.

يتم تنفيذ هذه المهام آليًا، في رمز برمجي يوفّره البائع عند بدء مزاد إعلانات من خلال استدعاء دالة 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() الوسيطات التالية:

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

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

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

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

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

كل مراجع Protected Audience API

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

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