تقديم عرض سعر في مزاد لشراء شريحة إعلانية

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

في مزاد "الجمهور المحمي"، عليك توفير المنطق لإنشاء عرض السعر، ويحتسب المتصفّح عرض السعر باستخدام هذا المنطق. هذا على عكس بُنى المزادات الأخرى التي تقدم فيها عرض السعر مباشرةً بدلاً من تقديم المنطق.

عليك توفير منطق إنشاء عرض السعر في دالة JavaScript generateBid() وتتم استضافة الملف على خادمك. عند إضافة مستخدم إلى مجموعة اهتمامات، يتم تمرير موقع هذا الملف إلى إعدادات مجموعة الاهتمامات باعتباره biddingLogicUrl.

خلال المزاد، يجلب المتصفّح منطق عروض أسعارك المحدّد في حقل biddingLogicUrl وينفّذ دالة generateBid() لكل مجموعة اهتمامات في بيئة آمنة معزولة تكون محدودة في تواصلها مع سياق خارجي. عند تنفيذ generateBid()، يمرِّر المتصفِّح إشارات إلى الدالة كوسيطات. وتحتوي هذه الإشارات على معلومات مختلفة من مصادر مختلفة، مثل بيانات الطرف الأول للناشر وبيانات البائع والبيانات في الوقت الفعلي وغيرها. يمكنك استخدام هذه الإشارات لحساب عرض السعر، ويتم عرض القيمة من طلب generateBid(). بعد إرسال عروض الأسعار، سينفذ المتصفح منطق نقاط البائع في كل عرض سعر لحساب درجة الرغبة لدى البائع.

generateBid()

يوضّح ما يلي وسيطات الدالة generateBid() وبنية عرض السعر الذي يتم عرضه من الدالة:


generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

الوسيطات

يستخدم generateBid() الوسيطات التالية:

الوسيطة Role

interestGroup

 كائن تم تمريره إليه من قبل مشتري الإعلان. قد يتم تعديل مجموعة الاهتمامات باستخدام dailyUpdateUrl.

auctionSignals

 موقع لوسيطة إعدادات المزاد يمرّره البائع إلى navigator.runAdAuction(). وهذا يوفر معلومات عن سياق الصفحة (مثل حجم الإعلان والرقم التعريفي للناشر) ونوع المزاد (السعر الأول أو السعر الثاني) والبيانات الوصفية الأخرى.

perBuyerSignals

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

trustedBiddingSignals

 يشير ذلك المصطلح إلى كائن تكون مفاتيحه trustedBiddingSignalsKeys الخاصة بمجموعة الاهتمامات، ويتم عرض قيمه في طلب trustedBiddingSignals.

browserSignals

 عنصر تم إنشاؤه من خلال المتصفّح، وقد يتضمّن معلومات حول سياق الصفحة (مثل hostname من الصفحة الحالية، والتي يمكن أن يزيّفها البائع) وبيانات لمجموعة الاهتمامات نفسها (مثل سجلّ لتاريخ فوز المجموعة في السابق بمزاد، للسماح بتحديد عدد مرّات الظهور على الجهاز فقط)

directFromSellerSignals

 الإشارات التي يمكن ضمان تلقّيها من بائع محدّد، على عكس auctionSignals وsellerSignals التي يمكن أن ترد من أي مشارك في سياق تنفيذ runAdAuction

إشارات المتصفّح

يحتوي الكائن browserSignals على السمات التالية:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}
الموقع الوصف

topWindowHostname

 اسم المضيف لمكان إجراء استدعاء runAdAuction().

seller

 البائع الذي تم إرسال عرض السعر إليه. في مزاد المكوّنات، تكون هذه القيمة هي بائع المكوّن.

topLevelSeller

 البائع من المستوى الأعلى في مزاد مكوّن من مكوّنات، ويتوفّر فقط في مزاد مكوّنات.

requestedSize

 تنصح السمة requestedSize بحجم إطار للمزاد. يحدّد البائع المقاس المطلوب في إعدادات المزاد، وتصبح القيمة متاحة لمقدّمي عروض الأسعار في generateBid(). قد يختار مقدِّمو عروض الأسعار في المزاد حجم محتوى مختلفًا للإعلان، وسيتم تغيير الحجم الناتج بصريًا ليلائم حجم حاوية العنصر.

joinCount

 يشير الحقل joinCount إلى عدد مرات انضمام هذا الجهاز إلى مجموعة الاهتمامات المشتركة هذه في آخر 30 يومًا أثناء تخزين مجموعة الاهتمامات بشكل مستمر (أي ما مِن فجوات في مساحة التخزين لمجموعة الاهتمامات على الجهاز بسبب انتهاء مغادرتها أو انتهاء صلاحية الاشتراك).

recency

 الحقل recency هو المدة الزمنية (بالدقائق) منذ انضمام هذا الجهاز إلى مجموعة الاهتمامات هذه حتى الآن.

bidCount

 عدد المرّات التي أرسلت فيها مجموعة الاهتمامات المشتركة عرض سعر.

prevWinsMs

 ويحتوي الحقل prevWinMs على الإعلانات الفائزة لمجموعة الاهتمامات، والوقت منذ مرات الفوز السابقة بالمللي ثانية. تجدر الإشارة إلى أنّ عنصر الإعلان هنا يحتوي فقط على حقلَي renderURL والبيانات الوصفية.

wasmHelper

 كائن WebAssembly.Module يعتمد على biddingWasmHelperURL لمجموعة الاهتمامات.

dataVersion

 قيمة إصدار البيانات من ردود خدمة المفتاح/القيمة لدى المشتري.

adComponentsLimit

 الحد الأقصى لعدد مكونات الإعلان التي يمكن أن يعرضها generateBid()

حساب عرض سعر

لاحتساب قيمة عرض السعر، يمكن أن يستخدم الرمز في generateBid() خصائص معلَمات الدالة.

مثال:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

إرجاع عرض سعر

تعرض دالة generateBid() كائنًا بالخصائص التالية:

الموقع Role
ad البيانات الوصفية العشوائية عن الإعلان، مثل المعلومات التي يتوقّع البائع أن يعرفها عن عرض السعر هذا أو تصميم الإعلان. يستخدم البائع هذه المعلومات في مزاده ومنطق اتخاذ القرار.
adCost قيمة رقمية تُستخدَم لتمرير النقرات التي يجريها المعلِن أو تكلفة الإحالة الناجحة من generateBid إلى reportWin. وتقتصر دقة هذا الرقم على حصان مانتيسا 8 بت وأس ذي 8 بت، مع إجراء أي تقريب على السطح.
adComponents قائمة اختيارية تضم ما يصل إلى 20 مكوّنًا للإعلانات المؤلفة من عدة قطع، وهي مأخوذة من السمة adComponents لوسيطة مجموعة الاهتمامات التي تم تمريرها إلى navigator.joinAdInterestGroup().
allowComponentAuction قيمة منطقية تشير إلى ما إذا كان يمكن استخدام عرض السعر هذا في مزاد مكوّنات ويتم ضبط القيمة على "خطأ" تلقائيًا إذا لم يتم تحديدها.
bid عرض سعر رقمي يدخل المزاد. يجب أن يكون البائع في وضع يسمح له بمقارنة عروض الأسعار من مشترين مختلفين، وبالتالي يجب أن تكون عروض الأسعار في وحدة يختارها البائع (على سبيل المثال"دولار أمريكي لكل ألف"). وإذا كان عرض السعر صفرًا أو سالبًا، لن تشارك مجموعة الاهتمامات هذه في مزاد البائع على الإطلاق. وباستخدام هذه الآلية، يمكن للمشتري تنفيذ أي قواعد خاصة بالمعلنين في ما يتعلق بالأماكن التي قد تظهر أو لا تظهر فيها إعلاناتهم.
bidCurrency عملة عرض السعر، وتُستخدَم في التحقّق من العملة.
render قاموس يصف تصميم الإعلان الذي يجب عرضه إذا فاز عرض السعر هذا بالمزاد. وتتضمّن المزايا ما يلي:
  • url: عنوان URL لتصميم الإعلان.
  • width: عرض تصميم الإعلان. ستتم مطابقة هذا الحجم مع البيان في مجموعة الاهتمامات، وسيتم استبداله في أي وحدات ماكرو لحجم الإعلان موجودة في عنوان URL لتصميم الإعلان. عند تحميل الإعلان في إطار مضمّن مستقل، يتم تجميد الإطار الداخلي للإطار المحمي (مثلاً الحجم المرئي لتصميم الإعلان) إلى هذا الحجم، وسيتعذّر عليه رؤية التغييرات في حجم الإطار الذي أجرته أداة التضمين.
  • height: ارتفاع تصميم الإعلان. اطّلِع على التفاصيل في width.

modelingSignals

 تم تمرير عدد صحيح من 0 إلى 4095 (12 بت) إلى reportWin() مع تشويش، كما هو موضَّح في مخطط التشويش والتجميع. وسيتم تجاهل القيم غير الصالحة، مثل القيم السالبة واللانهائية وNaN، ولن يتم تمريرها. سيتم اجتياز أقل 12 بت فقط.


يمكن للمشتري استخدام الإشارات المتاحة داخل الدالة generateBid()، بما في ذلك البيانات من بيانات المشترين التابعة للطرف الأول التي تم تسجيلها خلال وقت إنشاء مجموعة الاهتمامات في userBiddingSignals، للحصول على بعض القيم التي تم ضبطها في وظيفة إعداد تقارير اكتساب المشتري لتفعيل تدريب نموذج تعلُّم الآلة.