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

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

دليل 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 معزولة لا يمكنها التفاعل مع المحتوى الخارجي.

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() الوسيطات التالية:

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

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

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

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

جميع مراجع 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.