اطّلِع على كيفية ضبط مزاد Protected Audience API.
مزادات على الجهاز فقط يُديرها البائعون
يُقام مزاد "الجمهور المحمي" على الجهاز فقط على موقع إلكتروني يبيع مساحات إعلانية، ونشير إلى الجهة التي تُجري المزاد على أنّها البائع. قد تتصرّف العديد من الأطراف كبائعين: قد ينفّذ أحد المواقع الإلكترونية مزادًا إعلانيًا خاصًا به، أو قد يتضمّن نصًا برمجيًا تابعًا لجهة خارجية لإجراء المزاد نيابةً عنه، أو قد يستخدم نظام SSP الذي يجمع بين إجراء مزاد على الجهاز مع أنشطة مزاد إعلانات أخرى من جهة الخادم. يتمتع البائعون بثلاث وظائف أساسية في مزاد الإعلانات على الجهاز فقط:
- يقرر البائعون (أ) المشترين الذين يمكنهم المشاركة، و (ب) أي من عروض الأسعار من مجموعات اهتمامات المشترين مؤهلون للمشاركة في المزاد. يتيح ذلك للبائع فرض قواعد الموقع الإلكتروني بشأن الإعلانات المسموح لها بالظهور على الصفحة.
- البائعون مسؤولون عن منطق الأعمال الخاص بالمزاد: رمز JavaScript الذي يراعي السعر والبيانات الوصفية لكل عرض سعر، ويحسب نتيجة "الرغبة". ويفوز عرض السعر الذي حصل على أعلى درجة من الرغبة في المزاد.
- ويقدم البائعون تقارير حول نتيجة المزاد، بما في ذلك المعلومات المتعلقة بتوضيح السعر وأي دفعات أخرى. كما يحصل المشترون الفائزون والخاسرون على إعداد التقارير الخاصة بهم.
سيوضّح هذا المستند كيفية ضبط وبدء مزاد على الجهاز فقط.
ضبط مزاد إعلانات في Protected Audience API
لإجراء مزاد إعلانات في Protected Audience API، تتمثّل الخطوة الأولى في ضبط المزاد. ويتم ذلك من خلال إنشاء كائن auctionConfig
.
وفي ما يلي مثال على أحد هذه الإعدادات:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig
مكانًا للإقامة
السمات المطلوبة
إنّ السمات الوحيدة المطلوبة للسمة auctionConfigs
هي seller
وdecisionLogicUrl
وinterestGroupBuyers
.
الموقع | مثال | Role |
---|---|---|
seller | https://seller.example | مصدر البائع. |
decisionLogicUrl | https://seller.example/decision-logic.js | عنوان URL الخاص بالوظيفة المنطقية لقرار JavaScript للمزاد. يجب أن يكون لهذا الحقل المصدر نفسه الذي يتضمّن حقل البائع. |
interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
مصادر جميع مالكي مجموعات الاهتمامات الذين طلبوا تقديم عروض أسعار في المزاد |
السمات الاختيارية
أما السمات المتبقية في auctionConfigs
، فهي اختيارية.
الموقع | مثال | Role |
---|---|---|
trustedScoringSignalsUrl | https://seller.example/scoring-signals | عنوان URL لخادم المفتاح/القيمة الخاص بالبائعين. سيتم الاستعلام عن ذلك أثناء عملية تسجيل تقييم الإعلان باستخدام عنوان URL لعرض تصميم الإعلان كمفتاح أساسي. يجب أن يكون لهذا الحقل المصدر نفسه الذي يتضمّن حقل البائع. |
auctionSignals | {"category":"news"} | عنصر JSON متسلسل يمثِّل الإشارات المتاحة لجميع المشترين والبائعين المشارِكين في المزاد |
sellerSignals | {...} | عنصر JSON قابل للتسلسل ويمثّل الإشارات المتاحة للبائعين فقط |
perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
الإشارات المتاحة لمشترٍ محدّد ويمكن أن تأتي الإشارات من البائعين وكذلك المشترين أنفسهم. |
perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
الحد الأقصى لوقت التشغيل بالمللي ثانية من النص البرمجي generateBid() لمشترٍ معيّن سيتم تطبيق رمز حرف بدل على كل مشترٍ لم يتم تحديد مهلة محددة له. |
sellerTimeout | 100 | الحد الأقصى لوقت التشغيل بالمللي ثانية من النص البرمجي ScoreAd() للبائع |
componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | تكوينات إضافية لمزادات المكوّنات. |
resolveToConfig | صواب|خطأ | تمثّل هذه السمة أسلوبًا منطقيًا يتم فيه توجيه الوعد الذي يتم عرضه من runAdAuction() لحلّه إلى FencedFrameConfig إذا كانت القيمة صحيحة (للاستخدام في <fencedframe>)، أو إلى عنوان URL غير شفاف urn:uuid في حال ضبطه على القيمة false (للاستخدام في إطار <iframe>). يتم ضبطها تلقائيًا على false. |
تقديم الإشارات بشكل غير متزامن
يمكن اختياريًا تقديم قيم بعض الإشارات (التي تم ضبطها من خلال الحقول auctionSignals
وsellerSignals
وperBuyerSignals
وperBuyerTimeouts
) كقيم غير ملموسة، ولكن في شكل وعود. ويسمح هذا لبعض أجزاء المزاد، مثل تحميل النصوص البرمجية والإشارات الموثوق بها، وإطلاق عمليات الوظائف المعزولة، بالتداخل مع الحوسبة (أو استرداد الشبكة) لتلك القيم. لن ترى نصوص العمل المصغَّرة سوى القيم التي تم حلها، وفي حال رفض أي وعد من هذا القبيل، سيتم إلغاء المزاد ما لم يفشل بالفعل أو تم إلغاء المزاد بطرق أخرى.
ضبط مزاد مع بائعين متعددين
في بعض الحالات، قد يرغب عدة بائعين في المشاركة في مزاد، حيث يتم نقل الفائزين في مزادات منفصلة إلى مزاد آخر يديره بائع آخر. وتُعرف هذه المزادات المنفصلة التي يتم تمريرها باسم مزادات المكوّنات.
لتسهيل مزادات المكوّنات هذه، يمكن أن يحتوي عنصر componentAuctions
على
إعدادات مزاد إضافية لمزاد مكونات كل بائع. وسيتم تمرير عرض السعر الفائز لكل من مزادات المكوّنات هذه إلى مزاد "المستوى الأعلى" الذي يتخذ القرار النهائي للمزاد. قد لا يكون
auctionConfig
من مزادات المكوّنات الخاصة بها
componentAuctions
خاصة بها. عندما يكون الحقل componentAuctions
غير فارغ،
يجب أن يكون الحقل interestGroupBuyers
فارغًا. وهذا يعني أنّه بالنسبة إلى أي مزاد معيّن لـ "جمهور محمي": إمّا أن يكون هناك بائع واحد وليس هناك مزادات لمكوِّنات، أو إذا كانت جميع عروض الأسعار تأتي من مزادات المكوّنات، ولا يمكن للمزاد ذي المستوى الأعلى
الاختيار إلا من بين الفائزين في مزادات المكوّنات.
إجراء المزاد
يلجأ البائع إلى تقديم طلب إلى متصفح المستخدم لبدء مزاد إعلانات من خلال استدعاء navigator.runAdAuction()
.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
تعرض المكالمة runAdAuction()
وعدًا يحلّ المشكلة. ولا يمكن لأي رمز في صفحة الناشر فحص الإعلان الفائز أو التعرّف على محتواه من خلال runAdAuction()
. إذا تم ضبط العلامة resolveToConfig
على "صحيح" في AuctionConfig
، يتم عرض الكائن FencedFrameConfig
والذي لا يمكن عرضه إلا في إطار مضمّن مستقل. في حال ضبط العلامة على "خطأ"، يتم عرض رقم URN مبهم يمكن عرضه في إطار iframe. ومن المحتمل أن يعرض RunAdAuction قيمة فارغة، ما يشير إلى أنّه لم يتم اختيار أي إعلان. في هذه الحالة، قد يختار البائع
عرض إعلان يستهدف المحتوى.