تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

أنت تقدّم منطق إنشاء عروض الأسعار في دالة 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() الوسيطات التالية:

الوسيطة	الدور
`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() كائنًا بالسمات التالية:

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