إعداد مزاد إعلانات على صفحة الناشر

تعرَّف على كيفية إعداد مزاد Protected Audience API.

المزادات على الجهاز فقط التي يديرها البائعون

يجري إجراء مزاد Protected Audience على الجهاز على موقع إلكتروني يبيع مساحات إعلانية، أو الإشارة إلى الطرف الذي يجري المزاد باعتباره البائع. قد تتصرف العديد من الأطراف البائعون: قد يُجري موقع إلكتروني مزاد إعلانات خاص به، أو قد يتضمّن جهة خارجية البرنامج النصي لإجراء المزاد عليه، أو قد يستخدم وسيط عرض إعلانات المورِّد (SSP) الذي يجمع بين إجراء المزاد على الجهاز فقط مع أنشطة مزاد الإعلانات الأخرى من جهة الخادم يمتلك البائعون ثلاث وظائف أساسية في مزاد الإعلانات على الجهاز فقط:

1. يحدّد البائعون (أ) المشترين الذين يمكنهم المشاركة و (ب) أي من عروض الأسعار من هؤلاء المشترين تكون مجموعات الاهتمامات مؤهلة للمشاركة في المزاد. يتيح ذلك فرض البائع قواعد الموقع بشأن الإعلانات المسموح لها بالظهور على .
2. البائعون مسؤولون عن منطق النشاط التجاري للمزاد: JavaScript تراعي سعر كل عرض سعر وبياناته الوصفية، وتحسب "الرغبة" الجودة. يفوز عرض الأسعار الذي يحقق أعلى نقاط الرغبة المزاد.
3. يقدم البائعون تقارير عن نتائج المزاد، بما في ذلك معلومات عن ومقاصة السعر وأي مدفوعات أخرى. يحصل المشترون الفائزون والخاسرون أيضًا لإعداد تقاريرهم الخاصة.

يشرح هذا المستند كيفية إعداد مزاد على الجهاز وبدؤه.

إعداد مزاد إعلانات 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 مكانًا للإقامة

ملاحظة: additionalBids غير متاح في التنفيذ الحالي لـ Protected Audience API اقرأ قسم المشاركون في المزاد في القسم المحمي شرح عن Audience API للحصول على مزيد من المعلومات

الخصائص المطلوبة

الخصائص الوحيدة المطلوبة لـ auctionConfigs هي seller، decisionLogicUrl، وinterestGroupBuyers.

الموقع	مثال	الدور
seller	https://seller.example	أصل البائع.
decisionLogicUrl	https://seller.example/decision-logic.js	عنوان URL الخاص بتطبيق منطق القرارات في JavaScript للمزاد. يجب أن يكون لهذا الحقل المصدر نفسه الوارد في حقل البائع.
interestGroupBuyers	[https://buyer-1.example، https://buyer-2.example، ...]	مصادر طلبات جميع مالكي مجموعات الاهتمامات تقديم عروض أسعار في المزاد

السمات الاختيارية

السمات المتبقية في auctionConfigs اختيارية.

الموقع	مثال	الدور
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>). وتكون القيمة التلقائية على "خطأ".

تقديم الإشارات بشكل غير متزامن

قيم بعض الإشارات (التي تم ضبطها من خلال 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 قيمة فارغة، إشارة إلى عدم اختيار أي إعلان. في هذه الحالة، قد يختار البائع عرض إعلان يستهدف المحتوى.