دليل 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](https://developers.google.cn/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=19&hl=ar)
- يزور أحد المستخدِمين موقعًا إلكترونيًا يعرض الإعلانات.
- ينفذ رمز البائع
navigator.runAdAuction()
. يحدد هذا أي المساحة الإعلانية للبيع ومن يمكنه تقديم عروض أسعار. يجب أن يتضمن البائعون أيضًا نصًا برمجيًا التي تحقق كل عرض سعر،scoreAd()
. - يتم تنفيذ رمز المشتري الذي تمت دعوته لإنشاء عرض سعر، وعنوان URL لإعلان ذي صلة. والمواد الإبداعية وغيرها من البيانات. يستطيع النص البرمجي لعرض الأسعار الاستعلام عن البيانات في الوقت الفعلي مثل ميزانية الحملة الإعلانية المتبقية من ميزانية المشتري خدمة المفتاح/القيمة.
- يسجِّل رمز البائع كل عرض سعر ويختار فائزًا. يستخدم هذا المنطق دالة قيمة عرض السعر والبيانات الأخرى تؤدي إلى تحقيق مدى الرغبة في عرض السعر. إعلانات لا يمكن تفوقها رفض الفائز بحسب المحتوى. يمكن للبائع استخدام ملفات تعريف الارتباط الخاصة به خدمة المفتاح/القيمة للبيانات في الوقت الفعلي.
- ويتم عرض الإعلان الفائز كقيمة مبهمة يتم عرضها في إطار مضمّن. كل من البائع لن يتمكّن الناشر من الاطّلاع على هذه القيمة.
- ويتم إبلاغ البائع والمشترين الفائزين عن المزاد.
متى يُجرى المزاد؟
يمكن إدارة Protected Audience API بشكل فردي أو من خلال المزادات الآلية. في حال أراد بائعون متعددون المزاد الآلي:
- يزور المستخدم موقعًا إلكترونيًا مشاركًا.
- يجري بائع آخر مزادًا آليًا للعثور على إعلان سياقي لشريحة إعلانية متاحة.
- يتمّ إجراء مزاد Protected Audience API.
- يقارن
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
تتوفر الأدلة المرجعية لواجهة برمجة التطبيقات:
- دليل المطوّرين حول Protected Audience API
- دليل مشتري الإعلانات حول مجموعات الاهتمامات وإنشاء عروض الأسعار للجمهور المحمي.
- دليل بائع الإعلانات حول مزادات الإعلانات للجمهور المحمي
- دليل إعداد التقارير عن نتائج المزادات
- أفضل ممارسات وقت استجابة مزاد الإعلانات للجمهور المحمي
- تحديد المشاكل في الجمهور المحمي وحلّها
يوفّر الشرح في Protected Audience API أيضًا تفاصيل حول إتاحة الميزات والقيود المفروضة عليها.