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

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

نظرة عامة

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

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

• joinAdInterestGroup() مهمة
  • ضبط علامات طلب الخادم
  • ضبط أرقام تعريف عرض الإعلانات
  • تحديد أولويات المجموعات المستندة إلى الاهتمامات
  • إعداد إشارات عروض الأسعار الموثوق بها
• generateBid() مهمة
  • قراءة إشارات المتصفّح
  • إرجاع عنوان URL للعرض
  • إرجاع معرّف إعداد التقارير

مجموعة الاهتمامات في "الشراء والبيع"

في ما يلي مثال على إعدادات مجموعة الاهتمامات لمزاد 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,
});

في ما يلي الاختلافات بين إعدادات "الاستهداف المستند إلى السلوك والاهتمامات" وإعدادات "مجموعة الاهتمامات على الجهاز":

• يتيح الحقل auctionServerRequestFlags ضبط علامات لإخبار المتصفّح بتجاهل بعض البيانات في حمولة مزاد "المزايدة والعائد".
• يمكن تحديد قيمة userBiddingSignals في مجموعة الاهتمامات، ولكن يُنصح بحذفها باستخدام العلامة omit-user-bidding-signals. يمكن توفير الإشارات المحذوفة باستخدام خدمة K/V.
• يتم ضبط الحقل adRenderId مع الحقل renderURL المرتبط به، ولكن سيصبح الحقل adRenderId فقط جزءًا من حمولة مزاد "العطاءات والمزادات". يجب أن يتطابق عنوان URL للعرض الذي تم إرجاعه من generateBid() لاحقًا خلال وقت المزاد مع عنوان URL للعرض المحدّد في "المجموعة المتكاملة".
• يتم تحديد أرقام التعريف الخاصة بإعداد التقارير في مجموعة B&A IG، ولكنّها غير مضمّنة في حمولة مزاد B&A. يجب أن يتطابق معرّف إعداد التقارير الذي يتم عرضه من generateBid() لاحقًا خلال وقت المزاد مع عنوان URL للعرض المحدّد في IG.
• لا يتم تضمين ad.metadata ومعرّفات التقارير في حمولة مزاد "العطاءات والشراء"، وبدلاً من ذلك، تصبح هذه البيانات متاحة من خلال استخدام خدمة Trusted Key/Value Service.

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

joinAdInterestGroup() مهمة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يمكن أن توفّر خدمة K/V البيانات المحذوفة التالية:

• userBiddingSignals إذا كان المشتري يستخدمها
• metadata المرتبط بكل إعلان
• adRenderId المرتبط بكل إعلان
• معرّف تتبّع الأداء

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

يوضّح المثال التالي أحد الأساليب التي يمكن تنفيذها:

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'
          }   
        },
      ]
    }
  })
});

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

إرجاع إشارة تعديل مجموعة الاهتمامات من K/V إذا لزم الأمر

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

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

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

generateBid() مهمة

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

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

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

{
  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:

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

بما أنّه تم حذف العنصر ads في حمولة مزاد "العطاءات والشراء"، يجب إعادة إنشاء عنوان 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
  ]
})

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

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()

بما أنّ معرّفات إعداد التقارير غير مضمّنة في حمولة مزاد "الشراء الآلي والمباشر"، يصبح المعرّف متاحًا 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.

يمكنك الانتقال إلى دليل معرّف الإبلاغ لمعرفة المزيد.

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

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

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

• مزيد من المعلومات حول إعدادات مزاد "العطاءات والشراء" في Chrome
• يمكنك تجربة Protected Audience مع B&A باتّباع الدرس التطبيقي حول الترميز الخاص بالاختبار المحلي الشامل.

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

• إذا كان لديك سؤال حول "خدمات عروض الأسعار والمزادات"، يمكنك فتح مشكلة في مستودع "خدمات عروض الأسعار والمزادات".