دليل ومراجع 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 لا يمكنها التواصل مع العالم الخارجي.
- يزور أحد المستخدِمين موقعًا إلكترونيًا يعرِض الإعلانات.
- ينفِّذ رمز البائع
navigator.runAdAuction()
. يحدّد هذا العمود المساحة الإعلانية المعروضة للبيع والمستخدمين الذين يمكنهم تقديم عروض أسعار يجب على البائعين أيضًا تضمين نص برمجي يسجّل كل عرض سعر،scoreAd()
. - يتم تنفيذ رمز المشتري المدعو لإنشاء عرض سعر وعنوان URL لتصميم إعلان ملائم وغير ذلك من البيانات. يمكن للنص البرمجي لعروض الأسعار طلب البحث عن البيانات في الوقت الفعلي، مثل ميزانية الحملة الإعلانية المتبقية، من خدمة المفتاح/القيمة للمشتري.
- يحدِّد رمز البائع قيمة كل عرض سعر ويختار فائزًا. يستخدم هذا المنطق قيمة عرض السعر والبيانات الأخرى التي تعرض مدى الرغبة في عرض السعر. ويتم رفض الإعلانات التي لا يمكنها التغلب على الفائز السياقي. يمكن للبائع استخدام خدمة المفاتيح/القيمة الخاصة به للحصول على البيانات في الوقت الفعلي.
- يتم عرض الإعلان الفائز كقيمة مبهمة يتم عرضها في إطار مضمّن مستقل. ولن يتمكن كل من البائع والناشر من عرض هذه القيمة.
- يتمّ إبلاغ البائع والمشترين الفائزين بالمزاد.
متى يتم إجراء المزاد؟
يمكن تشغيل Protected Audience API بشكل مستقل أو من خلال مزادات آلية. في مزاد آلي متعدد البائعين
- يزور المستخدم أحد المواقع الإلكترونية المشاركة.
- يجري بائع آخر مزادًا آليًا للعثور على إعلان سياقي لشريحة إعلانية متاحة.
- يتم تنفيذ مزاد Protected Audience API.
- يقارن
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
- دليل مشتري الإعلانات حول مجموعات الاهتمامات وإنشاء عروض الأسعار للجمهور المحمي.
- دليل بائع الإعلانات حول مزادات الإعلانات للجمهور المحمي
- دليل إعداد التقارير عن نتائج المزادات
- أفضل ممارسات وقت استجابة مزاد الإعلانات للجمهور المحمي
- تحديد المشاكل في الجمهور المحمي وحلّها
يوفّر الشرح في Protected Audience API أيضًا تفاصيل حول إتاحة الميزات والقيود المفروضة عليها.