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

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

جميع مراجع Protected Audience API

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

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

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