الدمج مع B&A بصفتك مشتريًا

خدمات عروض الأسعار والمزادات (B&A) هي مجموعة من الخدمات لمشتري الإعلانات وبائعيها التي تعمل في بيئة تنفيذ موثوقة (TEE) لتسهيل مزاد الجمهور المحمي (PA). يوضّح دليل المطوّر هذا كيفية دمج المشترِي مع مزاد إعلانات المنتجات في خدمة مقارنة الأسعار (B&A PA) لمتصفّح Chrome.

نظرة عامة

للمشاركة في مزاد "شرائح الجمهور المحمية" باستخدام "خدمات B&A"، يعدّل المشتري مجموعة الاهتمامات (IG) لتحسين الحمولة من أجل تحسين وقت استجابة المزاد.

يطلب المشتري تنفيذ مهام تحسين الحمولة التالية:

مجموعة الاهتمامات لـ B&A

في ما يلي مثال على إعداد مجموعة الاهتمامات لمزاد إعلانات المنتجات داخل التطبيق (B&A PA) مع تطبيق تحسين الحمولة:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

في ما يلي الاختلافات بين إعدادات مجموعات الاهتمامات على الجهاز والإعدادات على مستوى البائعين والناشرين:

الحقول B&A IG الإصدار المتوافق مع الأجهزة فقط من Instagram مضمّنة في الحمولة البرمجية لمزاد B&A
auctionServerRequestFlags مستعمَل لم يتم الاستخدام لا
userBiddingSignals غير مستحسن مستعمَل لا، إذا تم ضبط العلامة omit-user-bidding-signals
adRenderId في ads وadComponents مستعمَل لم يتم الاستخدام في حال ضبط العلامة omit-ads، لا يتوفّر adRenderId في ads إلا في browserSignals.prevWins من الحمولة. لا يتم تضمين adRenderId المحدَّد في adComponents في الحمولة.

إذا لم يتم ضبط العلامة omit-ads، تكون القيمة متوفّرة في browserSignals.prevWins وinterestGroup.adRenderIds وinterestGroup.adComponentRenderIds.
renderURL في ads وadComponents مستعمَل مستعمَل لا
metadata في ads وadComponents لم يتم الاستخدام مستعمَل لا
أرقام تعريف الإبلاغ في ads مستعمَل مستعمَل لا
  • يسمح حقل auctionServerRequestFlags بضبط علامات تطلب من المتصفّح حذف بعض البيانات في حمولة مزاد B&A.
  • يمكن تحديد قيمة userBiddingSignals في مجموعة الاهتمامات، ولكن يُنصح بحذفها باستخدام العلامة omit-user-bidding-signals. يمكن تقديم الإشارات التي تم حذفها باستخدام خدمة "مفتاح/قيمة".
  • يتمّ ضبط الحقل adRenderId مع الحقل renderURL المرتبط به، ولكنّ الحقل adRenderId فقط هو الذي سيصبح جزءًا من الحمّلة البرمجية لمزاد B&A. يجب أن يتطابق عنوان URL لعرض الإعلان الذي يتم إرجاعه من generateBid() لاحقًا خلال وقت المزاد مع عنوان URL لعرض الإعلان المحدّد في IG.
  • يتمّ تحديد أرقام تعريف إعداد التقارير في IG لإعلانات B&A، ولكنّها لا يتمّ تضمينها في الحمّولة لجلسة مزاد إعلانات B&A. يجب أن يتطابق رقم تعريف إعداد التقارير الذي تم إرجاعه من generateBid() لاحقًا خلال وقت المزاد مع عنوان URL لعرض الإعلان المحدّد في IG.
  • لا يتم تضمين ad.metadata ومعرّفات إعداد التقارير في الحمولة في مزاد B&A، وبدلاً من ذلك، تصبح هذه البيانات متاحة من خلال استخدام خدمة مفتاح/قيمة موثوق به.

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

joinAdInterestGroup() مهمة

يجب تنفيذ المهام التالية لمكالمة joinAdInterestGroup().

ضبط علامات طلب الخادم

يقبل الحقل auctionServerRequestFlags في ملف الإعدادات joinAdInterestGroup() العلامات التالية:

الإبلاغ الوصف
omit-user-bidding-signals تُهمِل العلامة omit-user-bidding-signals عنصر userBiddingSignals في الحمولة البرمجية للمزاد.

في حال عدم ضبط العلامة، ستصبح قيمة userBiddingSignals المحدّدة في مجموعة الاهتمامات متاحة داخل generateBid() من "خدمة عروض الأسعار".
omit-ads يطلب العلامة omit-ads من المتصفّح حذف كائنَي ads وadComponents في الحمولة الإعلانية للمزاد.

سيتوفّر adRenderId في prevWins في browserSignals.

في حال عدم ضبط العلامة، سيحتوي الحقلان adRenderIds وadComponentRenderIds في الوسيطة interestGroup من generateBid() على معرّفات عرض الإعلانات المقابلة.

ننصح المشترين بشدة باختيار علامة omit-ads. في وقت ما في المستقبل، قد يتم إيقاف إرسال معرّفات العرض ومعرّفات عرض مكوّنات الإعلان من العميل نهائيًا لتحسين الحمولة.

يتم التعامل مع البيانات التي تم حذفها من خلال إتاحة المعلومات ذات الصلة في trustedBiddingSignals. يمكن استخدام العلامات بشكلٍ فردي، ولا يلزم استخدامها معًا.

مثال على الاستخدام:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

ضبط أرقام تعريف عرض الإعلانات

لتقليل حجم الحمولة في مزاد B&A، يتم حذف العنصرَين ads وadComponents لمجموعة الاهتمامات، وبالتالي لا تتوفّر هذه العناصر داخل الدالة generateBid() التي يتم تشغيلها في خدمة عروض الأسعار.

للتعامل مع معلومات الإعلان غير المتوفّرة، يحتفظ المشتري بمعرّف (adRenderId وadComponentRenderId) مرتبط بكل إعلان في إعداد مجموعة الاهتمامات. يجب أن يكون المعرّف سلسلة DOMString بطول 12 بايت أو أقل. إذا كان المعرّف مشفَّرًا بترميز Base64، يجب أن يكون طوله 12 بايت أو أقل.

مثال على مجموعة اهتمامات تتضمّن أرقام تعريف عرض الإعلانات:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

تصبح adRenderId المرتبطة بالإعلانات متاحة في prevWins.browserSignals في generateBid().

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

ضبط أولويات مجموعات الاهتمامات

يسمح Chrome للمشترين بتحديد أولوية مجموعات الاهتمامات. إذا تمّ بلوغ الحدّ الأقصى لحجم الحمولة لكلّ مشترٍ الذي حدّده البائع، يتمّ استخدام قيم أولوية مجموعات الاهتمام لإلغاء مجموعات الاهتمام ذات الأولوية الأقلّ لمشترٍ واحد عند إنشاء حمولة مزاد B&A للبائع. لاختيار مجموعات الاهتمامات بين المشترين المختلفين، يقرّر المتصفّح ذلك استنادًا إلى حجم الحمولة التسلسلية. يتم تلقائيًا منح كل مشترٍ حجمًا متساوٍ. يُرجى العِلم أنّ تحديد الأولوية الفعلي يحدث على خوادم B&A، وليس عند إنشاء الحمولة المطلوبة.

يتم احتساب الأولوية في وقت المزاد باستخدام متجهات الأولوية الخاصة بالمشتري (priorityVector) وإشارات الأولوية الخاصة بالبائع (prioritySignals). ويمكن للمشتري إلغاء إشارات الأولوية الخاصة بالبائع.

الموقع الوصف
متّجه الأولوية يقدّم المشتري المتجهات كقيمة مفتاح priorityVector من خدمة "مفاتيح/قيم".
الإشارات ذات الأولوية يقدّم البائع الإشارات من خلال ضبط priority_signals من إعدادات المزاد.
إلغاء الإشارات ذات الأولوية يقدّم المشتري القيمة المُلغاة في حقل priority_signals_overrides من PerBuyerConfig في إعدادات المزاد.

أثناء المزاد، يحسب المتصفّح حاصل ضرب نقطي للعناصر المتفرقة للمفاتيح المطابقة في priorityVector وprioritySignals حسب الأولوية. في الرسم البياني التالي، يتم احتساب الأولوية حسب (4 * 2) + (3 * -1) التي يتم تقليلها إلى 8 + -3، وبالتالي تكون أولوية مجموعة الاهتمامات هذه في وقت المزاد هي 5.

يتم ضرب كل مفتاح في متجه الأولوية وعناصر إشارات الأولوية ببعضها، ثم تجميع النتائج معًا لاحتساب الأولوية.
الشكل 1: احتساب الأولوية باستخدام متجهات المشتري وإشارات البائع

تتوفّر أيضًا إشارات إضافية لاستخدامها في تحديد الأولوية في "الحملات على شبكة البحث" و"الحملات على شبكة Google الإعلانية":

Signal الوصف
deviceSignals.one تكون القيمة دائمًا 1، وهي مفيدة لإضافة ثابت إلى المنتج النقطي.
deviceSignals.ageInMinutes تصف القيمة عمر مجموعة الاهتمامات (الوقت منذ آخر عملية انضمام إلى مجموعة الاهتمامات) بالدقائق كعدد صحيح بين 0 و43,200.
deviceSignals.ageInMinutesMax60 تصف القيمة ما تعنيه إشارة ageInMinutes نفسها، ولكن الحد الأقصى لها هو 60. إذا مرّ أكثر من ساعة على إنشاء المجموعة، يتم عرض 60.
deviceSignals.ageInHoursMax24 تصف القيمة عمر المجموعة ذات الاهتمامات المشتركة بالساعات، ويكون الحد الأقصى لها 24 ساعة. إذا مرّ أكثر من يوم على إنشاء المجموعة، يتم عرض القيمة 24.
deviceSignals.ageInDaysMax30 تصف القيمة عمر المجموعة ذات الاهتمامات المشتركة بالأيام، والحد الأقصى هو 30 يومًا. إذا مرّ أكثر من 30 يومًا على إنشاء المجموعة، يتم عرض 30.

لمزيد من المعلومات، يُرجى الانتقال إلى الشرح على GitHub.

إعداد إشارات عروض الأسعار الموثوق بها

بما أنّه سيتم حذف بعض البيانات من الحمولة في مزاد B&A، يمكنك استخدام خدمة Key/Value لتوفير البيانات التي تم حذفها كإشارات عروض أسعار موثوق بها لدالة generateBid().

يمكن أن تقدّم خدمة "مفتاح/قيمة" البيانات التالية التي تم حذفها:

  • userBiddingSignals إذا استخدمها المشتري
  • metadata المرتبطة بكل إعلان
  • adRenderId المرتبطة بكل إعلان
  • معرّف تتبّع الأداء
يمكن إرسال البيانات التي تم حذفها من مجموعة الاهتمامات إلى خادم جمع بيانات المشتري. يُرسِل خادم الجمع البيانات إلى خدمة المفاتيح/القِيم، وفي وقت لاحق، يحمِّل المتصفّح هذه البيانات من خدمة المفاتيح/القِيم.
الشكل 2: مثال على إعداد الإشارات الموثوق بها

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

يوضّح المثال التالي نهجًا واحدًا يمكن تنفيذه:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

في المثال، يتمّ تحديد معرّف فريد لوحدة IG ويصبح جزءًا من مفتاح الإشارات الموثوق بها. يتم إرسال مفتاح IG والقيم المرتبطة به إلى خادمك ليتم تحميلها في خدمة إدارة مفاتيح التشفير. وفي وقت لاحق خلال المزاد، يُجلب المتصفّح الإشارات الموثوق بها ويُتاحها في دالة generateBid() الخاصة بالمشتري.

عرض إشارة تعديل مجموعة الاهتمامات من مفتاح/قيمة إذا لزم الأمر

يتم استخدام مفتاح updateIfOlderThanMs للإشارات الموثوق بها لتعديل مجموعة الاهتمامات قبل الفاصل الزمني اليومي المعتاد. إذا لم يتمّ الانضمام إلى مجموعة الاهتمامات أو تعديلها خلال فترة زمنية تتجاوز قيمة المللي ثانية التي يتمّ عرضها لمفتاح updateIfOlderThanMs، سيتمّ تعديل مجموعة الاهتمامات باستخدام آلية updateURL. يُرجى العِلم أنّ Chrome لن يعدّل مجموعات الاهتمامات أكثر من مرة كل 10 دقائق.

إذا أظهر مزاد B&A إعلانًا فائزًا لا يتطابق مع أحد الإعلانات المحدّدة في مجموعة الاهتمامات المخزّنة في المتصفّح، سيُفشل المتصفّح المزاد. يمكن أن تكون آلية updateIfOlderThanMs مفيدة في التأكّد من أنّ المتصفّح ومزاد B&A يتفقان على مجموعة الإعلانات في مجموعة الاهتمامات.

يُرجى الانتقال إلى الشرح لمعرفة المزيد.

generateBid() مهمة

يجب تنفيذ المهام التالية لمكالمة generateBid().

قراءة إشارات المتصفّح

يبدو عنصر browserSignals الذي تم تمريره إلى طلب B&A generateBid() على النحو التالي:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

تتوفّر السمات المعدَّلة أو الجديدة التالية في browserSignals:

الموقع الوصف
prevWins prevWins هو صفيف من مجموعات ثنائية من الوقت والإعلان. يمثّل الوقت الثواني التي مضت منذ الفوز السابق للإعلان المرتبط في آخر 30 يومًا.

تم تعديله لتقديم adRenderId بدلاً من عنصر ad.
wasmHelper عنصر مجمّع للرمز المقدَّم من biddingWasmHelperURL.
dataVersion قد يتضمّن الخادم الموثوق به رأس استجابة رقميًا من النوع Data-Version اختياريًا، والذي يصبح متاحًا في generateBid().

يمكنك الاطّلاع على الشرح على GitHub للحصول على مزيد من المعلومات.

عنوان URL لعرض المنتج المراد إرجاعه من generateBid()

بما أنّ عنصر ads تم حذفه من الحمولة في مزاد B&A، يجب إعادة إنشاء عنوان URL لعرض الإعلان الذي تم إرجاعه من generateBid(). يتم تحديد كيفية إعادة إنشاء عنوان URL لعرض الإعلان من خلال عملية التنفيذ، ويجب أن يتطابق عنوان URL المعروض مع عنوان URL لعرض الإعلان المحدّد في مجموعة الاهتمامات.

من بين الطرق التي يمكن اتّباعها الاحتفاظ بعنوان URL أساسي وملء النموذج بالمعلومات الواردة من interestGroup وtrustedBiddingSignals.

في هذا المثال، نحدّد 4 إعلانات استنادًا إلى اللون والمنتج:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

بعد ذلك، نرسل اللون المفضّل للمستخدم ومعلومات المنتج ليتم تحميلها في خدمة "المفتاح/القيمة":

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

في وقت لاحق، عند تنفيذ المزاد، تصبح إشارات عروض الأسعار الموثوق بها متاحة في generateBid()، ويمكن استخدام هذه المعلومات لإعادة إنشاء عنوان URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

عرض أرقام تعريف الإبلاغ من generateBid()

بما أنّ معرّفات إعداد التقارير غير مضمّنة في الحمولة في مزاد B&A، يصبح المعرّف متاحًا generateBid() من خلال إشارات عروض الأسعار الموثوق بها. بعد تحديد معرّف إعداد التقارير الذي سيتم استخدامه، يتم عرض معرّف إعداد التقارير الذي تم اختياره من generateBid(). يجب أن تتطابق أرقام التعريف المعروضة مع أرقام التعريف المحدّدة في مجموعة الاهتمامات.

في هذا المثال، يتم اختيار الإعلان 1، ويتم عرض معرّف العرض المرتبط به من generateBid():

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

يصبح رقم تعريف إعداد التقارير المعروض متوفّرًا في الفترة من ‎reportWin() إلى ‎buyerReportingSignals:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

إذا لم يتم عرض القيمة buyerReportingId من generateBid()، تكون القيمة interestGroupName متاحة في buyerReportingSignals بدلاً من buyerReportingId.

يُرجى الانتقال إلى دليل استخدام المعرّف التعريفي للإبلاغ للاطّلاع على مزيد من المعلومات.

الخطوات التالية

تتوفّر لك المراجع التالية:

مزيد من المعلومات

هل لديك أسئلة؟