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

اطّلِع على كيفية ضبط مزاد Protected Audience API.

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

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

السمات المطلوبة

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