به عنوان خریدار با B&A ادغام شوید

سرویس‌های پیشنهاد قیمت و حراج (B&A) مجموعه‌ای از خدمات برای خریداران و فروشندگان تبلیغات است که در یک محیط اجرای قابل اعتماد (TEE) اجرا می‌شود تا حراج مخاطبان محافظت‌شده (PA) را تسهیل کند. این راهنمای توسعه‌دهندگان توضیح می‌دهد که چگونه یک خریدار می‌تواند با یک حراج مخاطبان محافظت‌شده برای کروم ادغام شود.

نمای کلی

برای شرکت در یک حراج مخاطبان محافظت‌شده با خدمات B&A، خریدار گروه ذینفع (IG) را به‌روزرسانی می‌کند تا بار داده را برای بهبود تأخیر حراج بهینه‌سازی کند.

وظایف بهینه‌سازی بار مفید زیر توسط خریدار مورد نیاز است:

• وظایف joinAdInterestGroup()
  • پرچم‌های درخواست سرور را تنظیم کنید
  • تنظیم شناسه‌های رندر تبلیغات
  • تعیین اولویت‌های گروه‌های ذینفع
  • سیگنال‌های پیشنهاد قیمت قابل اعتماد تنظیم کنید
• وظایف generateBid()
  • خواندن سیگنال‌های مرورگر
  • برگرداندن آدرس رندر
  • شناسه گزارش بازگشت

گروه علاقه‌مندان به 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 و پیکربندی‌های روی دستگاه عبارتند از:

• فیلد auctionServerRequestFlags امکان تنظیم پرچم‌هایی را فراهم می‌کند که به مرورگر می‌گوید برخی از داده‌ها را در payload حراج B&A حذف کند.
• مقدار userBiddingSignals را می‌توان در گروه علاقه‌مندی تعریف کرد، اما توصیه می‌شود با استفاده از پرچم omit-user-bidding-signals آنها را حذف کنید. سیگنال‌های حذف شده را می‌توان با استفاده از سرویس K/V ارائه داد.
• فیلد adRenderId به همراه renderURL مربوطه تنظیم می‌شود، اما فقط adRenderId بخشی از payload حراج B&A خواهد شد. URL رندری که بعداً در طول زمان حراج از generateBid() برگردانده می‌شود باید با URL رندری که در IG تعریف شده است، مطابقت داشته باشد.
• شناسه‌های گزارش‌دهی در B&A IG تعریف شده‌اند، اما در بار داده حراج B&A گنجانده نشده‌اند. شناسه گزارش‌دهی که بعداً در طول زمان حراج از generateBid() برگردانده می‌شود، باید با URL رندر تعریف‌شده در IG مطابقت داشته باشد.
• شناسه‌های ad.metadata و گزارش‌دهی در payload حراج B&A گنجانده نشده‌اند و در عوض، این داده‌ها از طریق استفاده از سرویس Trusted Key/Value در دسترس قرار می‌گیرند.

توجه داشته باشید که renderURL ها و شناسه‌های گزارش‌دهی در ads هنوز در پیکربندی گروه علاقه‌مندی تعریف شده‌اند، اگرچه در بار داده درخواست حراج گنجانده نمی‌شوند، زیرا مرورگر بررسی می‌کند که URL رندر و شناسه‌های گزارش‌دهی بازگردانده شده از تابع generateBid() از سرویس پیشنهاد قیمت با مقادیر تعریف شده در گروه علاقه‌مندی مطابقت داشته باشند.

وظایف joinAdInterestGroup()

برای فراخوانی تابع joinAdInterestGroup() وظایف زیر باید انجام شوند.

پرچم‌های درخواست سرور را تنظیم کنید

فیلد auctionServerRequestFlags در پیکربندی joinAdInterestGroup() پرچم‌های زیر را می‌پذیرد:

داده‌های حذف‌شده با در دسترس قرار دادن اطلاعات مرتبط در trustedBiddingSignals مدیریت می‌شوند. پرچم‌ها می‌توانند به‌صورت جداگانه استفاده شوند و لازم نیست با هم استفاده شوند.

مثال استفاده:

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

تنظیم شناسه‌های رندر تبلیغات

برای کاهش اندازه‌ی بار داده‌ی حراج B&A، اشیاء ads و adComponents از گروه علاقه‌مندی حذف شده‌اند و در عوض، این اشیاء در داخل تابع generateBid() که در سرویس پیشنهاد قیمت اجرا می‌شود، در دسترس نیستند.

برای مدیریت اطلاعات آگهی از دست رفته، خریدار یک شناسه ( adRenderId و adComponentRenderId ) مرتبط با هر آگهی در پیکربندی گروه علاقه‌مندی را نگهداری می‌کند. شناسه باید یک DOMString با طول ۱۲ بایت یا کمتر باشد. اگر شناسه با Base64 کدگذاری شده باشد، طول آن باید ۱۲ بایت یا کمتر باشد.

یک گروه ذینفع نمونه با شناسه‌های رندر تبلیغات:

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() تولید شوند.

تعیین اولویت‌های گروه‌های ذینفع

کروم به خریداران اجازه می‌دهد تا گروه‌های مورد علاقه را اولویت‌بندی کنند. اگر محدودیت اندازه بار داده برای هر خریدار که توسط فروشنده تعیین شده است، محقق شود، آنگاه از مقادیر اولویت گروه مورد علاقه برای حذف گروه‌های مورد علاقه با اولویت پایین‌تر برای یک خریدار واحد هنگام ایجاد بار داده حراج B&A برای فروشنده استفاده می‌شود. برای انتخاب گروه‌های مورد علاقه بین خریداران مختلف، مرورگر بر اساس اندازه بار داده سریالی تصمیم می‌گیرد. به طور پیش‌فرض، به هر خریدار اندازه مساوی داده می‌شود. توجه داشته باشید که اولویت‌بندی واقعی در سرورهای B&A اتفاق می‌افتد، و نه زمانی که بار داده درخواست ایجاد می‌شود.

اولویت در زمان حراج با استفاده از بردارهای اولویت خریدار ( priorityVector ) و سیگنال‌های اولویت فروشنده ( prioritySignals ) محاسبه می‌شود. خریدار می‌تواند سیگنال‌های اولویت فروشنده را نادیده بگیرد.

در طول حراج، مرورگر حاصلضرب نقطه‌ای پراکنده کلیدهای منطبق در priorityVector و prioritySignals را برای اولویت محاسبه می‌کند. در نمودار زیر، اولویت با (4 * 2) + (3 * -1) محاسبه می‌شود که به 8 + -3 کاهش می‌یابد، بنابراین اولویت این گروه علاقه‌مند در زمان حراج 5 است.

سیگنال‌های اضافی نیز برای اولویت‌بندی در B&A در دسترس هستند:

برای کسب اطلاعات بیشتر، به توضیح‌دهنده در GitHub مراجعه کنید.

سیگنال‌های پیشنهاد قیمت قابل اعتماد تنظیم کنید

از آنجایی که برخی از داده‌ها از payload حراج B&A حذف می‌شوند، می‌توانید از سرویس Key/Value برای ارائه داده‌های حذف شده به عنوان سیگنال‌های پیشنهاد قیمت معتبر به تابع generateBid() استفاده کنید.

داده‌های حذف‌شده‌ی زیر می‌توانند توسط سرویس K/V ارائه شوند:

• userBiddingSignals در صورت استفاده توسط خریدار
• metadata مرتبط با هر تبلیغ
• adRenderId مرتبط با هر تبلیغ
• شناسه گزارش

یکی از رویکردهایی که می‌توان اتخاذ کرد این است که یک شناسه منحصر به فرد را در کلیدهای سیگنال‌های مناقصه معتبر قرار دهید و سپس داده‌های مرتبط را به سرور خود ارسال کنید تا بتوان آنها را در سرویس کلید/مقدار بارگذاری کرد. با این حال، پیاده‌سازی واقعی به فناوری تبلیغات بستگی دارد و API تجویزی نیست.

مثال زیر یکی از رویکردهای قابل پیاده‌سازی را شرح می‌دهد:

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 و مقادیر مرتبط با آن به سرور شما ارسال می‌شوند تا در سرویس Key/Value بارگذاری شوند. در زمان بعدی در طول حراج، مرورگر سیگنال‌های مورد اعتماد را دریافت کرده و آنها را در تابع generateBid() خریدار در دسترس قرار می‌دهد.

در صورت نیاز، سیگنال به‌روزرسانی گروه ذینفع را از K/V برگردانید

کلید updateIfOlderThanMs برای سیگنال‌های مورد اعتماد، برای به‌روزرسانی گروه علاقه‌مندی زودتر از بازه زمانی معمول روزانه استفاده می‌شود. اگر گروه علاقه‌مندی در مدت زمانی بیش از مقدار میلی‌ثانیه برگردانده شده برای کلید updateIfOlderThanMs عضو نشده یا به‌روزرسانی نشده باشد، گروه علاقه‌مندی با مکانیسم updateURL به‌روزرسانی خواهد شد. توجه داشته باشید که کروم گروه‌های علاقه‌مندی را بیشتر از هر 10 دقیقه یک بار به‌روزرسانی نمی‌کند.

اگر حراج B&A یک تبلیغ برنده را برگرداند که با یکی از تبلیغات تعریف شده در گروه علاقه‌مندی ذخیره شده در مرورگر مطابقت نداشته باشد، مرورگر در حراج شکست می‌خورد. مکانیسم updateIfOlderThanMs می‌تواند در اطمینان از توافق مرورگر و حراج B&A در مورد مجموعه تبلیغات در گروه علاقه‌مندی مفید باشد.

برای کسب اطلاعات بیشتر به توضیح دهنده مراجعه کنید.

وظایف 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 در payload حراج B&A حذف شده است، URL رندر شده‌ای که از generateBid() برگردانده می‌شود باید دوباره ایجاد شود. نحوه بازسازی URL رندر شده توسط پیاده‌سازی شما تعیین می‌شود و URL برگردانده شده باید با URL رندر شده تعریف شده در گروه مورد نظر مطابقت داشته باشد.

یک رویکرد که می‌توان اتخاذ کرد، حفظ یک URL پایه و پر کردن الگو با اطلاعات interestGroup و trustedBiddingSignals است.

در این مثال، ما ۴ تبلیغ را بر اساس رنگ و محصول تعریف می‌کنیم:

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

از آنجایی که شناسه‌های گزارش‌دهی در payload حراج B&A گنجانده نشده‌اند، این شناسه از طریق سیگنال‌های پیشنهاد قیمت معتبر برای generateBid() در دسترس قرار می‌گیرد. پس از تعیین شناسه گزارش‌دهی مورد استفاده، شناسه گزارش‌دهی انتخاب شده از generateBid() بازگردانده می‌شود. شناسه‌های بازگردانده شده باید با شناسه‌های تعریف شده در گروه علاقه‌مند مطابقت داشته باشند.

در این مثال، تبلیغ ۱ انتخاب شده است و شناسه رندر مرتبط با آن از generateBid() برگردانده می‌شود:

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

شناسه گزارش برگشتی از طریق buyerReportingSignals در reportWin() در دسترس قرار می‌گیرد:

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

اگر تابع generateBid() buyerReportingId را برنگرداند، آنگاه مقدار interestGroupName به جای buyerReportingId در buyerReportingSignals موجود است.

برای کسب اطلاعات بیشتر به راهنمای شناسه گزارش‌دهی مراجعه کنید.

مراحل بعدی

منابع زیر برای شما در دسترس است

بیشتر بدانید

• درباره تنظیمات حراج B&A در Chrome بیشتر بدانید
• با دنبال کردن آزمایشگاه کد تست محلی سرتاسری، با مخاطب محافظت‌شده با B&A آزمایش کنید.

سوالی دارید؟

• اگر در مورد خدمات مناقصه و مزایده سوالی دارید، در مخزن خدمات B&A یک موضوع (issue) باز کنید .