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

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

المزادات التي يجريها البائعون على الأجهزة

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

  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.

الموقع مثال الدور
seller https://seller.example تمثّل هذه السمة بلد البائع.
decisionLogicUrl https://seller.example/decision-logic.js عنوان URL لـ worklet منطق اتّخاذ القرار في 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 true|false قيمة منطقية توجّه الوعد الذي تم إرجاعه من runAdAuction() إلى FencedFrameConfig إذا كانت القيمة صحيحة (للاستخدام في <fencedframe>)، أو إلى عنوان URL غير شفاف urn:uuid إذا كانت القيمة خاطئة (للاستخدام في <iframe>). القيمة التلقائية هي "خطأ".

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

يمكن تقديم قيم بعض الإشارات (التي يتم ضبطها من خلال الحقول auctionSignals وsellerSignals وperBuyerSignals وperBuyerTimeouts) بشكل اختياري ليس كقيم محددة، بل كـ Promises. ويسمح ذلك بتداخل بعض أجزاء المزاد، مثل تحميل النصوص البرمجية والإشارات الموثوقة، وإطلاق عمليات worklet معزولة، مع عملية الحساب (أو استرجاع الشبكة) لهذه القيم. لن ترى نصوص Worklet البرمجية سوى القيم التي تم حلّها. وفي حال تم رفض أي وعد من هذا النوع، سيتم إلغاء المزاد ما لم يكن قد تعذّر أو تم إلغاؤه بطرق أخرى.

إعداد مزاد يضمّ بائعين متعدّدين

في بعض الحالات، قد يريد عدة بائعين المشاركة في مزاد، مع نقل الفائزين في مزادات منفصلة إلى مزاد آخر يديره بائع آخر. تُعرف المزادات المنفصلة التي يتمّ تمريرها باسم مزادات المكوّنات. لتسهيل مزادات المكوّنات هذه، يمكن أن يحتوي الكائن componentAuctions على إعدادات مزاد إضافية لكل مزاد مكوّنات خاص بالبائع. سيتم نقل عرض السعر الفائز في كل مزاد من هذه المكونات إلى المزاد "الأعلى مستوى" الذي يتخذ القرار النهائي بشأن المزاد. قد لا يكون لدى auctionConfig مزادات المكوّنات componentAuctions خاص بها. عندما تكون قيمة componentAuctions غير فارغة، يجب أن تكون قيمة interestGroupBuyers فارغة. أي أنّه في أي مزاد معيّن في Protected Audience، إمّا أن يكون هناك بائع واحد ولا توجد مزادات على مستوى المكوّنات، أو أنّ جميع عروض الأسعار تأتي من مزادات على مستوى المكوّنات ولا يمكن للمزاد على المستوى الأعلى الاختيار إلا من بين الفائزين في مزادات المكوّنات.

إجراء المزاد

يرسل البائع طلبًا إلى متصفّح المستخدم لبدء مزاد إعلاني من خلال استدعاء navigator.runAdAuction().

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

تعرض الدالة runAdAuction() وعدًا يتم تنفيذه للإعلان. لا يمكن لأي رمز في صفحة الناشر فحص الإعلان الفائز أو معرفة محتواه بأي طريقة أخرى من نتيجة runAdAuction(). إذا تم ضبط العلامة resolveToConfig على true في AuctionConfig، سيتم عرض الكائن FencedFrameConfig الذي لا يمكن عرضه إلا في إطار محصور. إذا تم ضبط العلامة على "خطأ"، سيتم عرض URN غير شفاف يمكن عرضه في إطار iframe. من المحتمل أن تعرض الدالة runAdAuction قيمة فارغة، ما يشير إلى أنّه لم يتم اختيار أي إعلان. في هذه الحالة، قد يختار البائع عرض إعلان يستهدف المحتوى.