این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

نمای کلی

برای شرکت در حراج مخاطب محافظت شده با خدمات 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 و گروه مورد علاقه روی دستگاه عبارتند از:

فیلدها	B&A IG	IG روی دستگاه	در محموله حراج B&A گنجانده شده است
`auctionServerRequestFlags`	استفاده می شود	استفاده نشده است	خیر
`userBiddingSignals`	توصیه نمی شود	استفاده می شود	خیر، اگر پرچم `omit-user-bidding-signals` تنظیم شده باشد
`adRenderId` در `ads` و `adComponents`	استفاده می شود	استفاده نشده است	اگر پرچم `omit-ads` تنظیم شده باشد، `adRenderId` در `ads` فقط در `browserSignals.prevWins` از payload موجود است. `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 آنها را حذف کنید. سیگنال های حذف شده را می توان با استفاده از سرویس K/V تامین کرد.
فیلد adRenderId همراه با renderURL مرتبط تنظیم شده است، اما فقط adRenderId بخشی از محموله مزایده B&A خواهد شد. URL رندری که بعداً در طول زمان حراج از generateBid() برگردانده می شود باید با URL رندر تعریف شده در IG مطابقت داشته باشد.
شناسه های گزارش در IG B&A تعریف شده اند، اما در محموله مزایده B&A گنجانده نشده اند. شناسه گزارشی که بعداً در طول زمان حراج از generateBid() برگردانده می شود باید با URL رندر تعریف شده در IG مطابقت داشته باشد.
ad.metadata و شناسه‌های گزارش در محموله مزایده B&A گنجانده نشده‌اند، و در عوض، این داده‌ها از طریق استفاده از سرویس کلید/ارزش معتمد در دسترس می‌شوند.

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

`joinAdInterestGroup()` وظایف

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

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

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

پرچم توضیحات

omit-user-bidding-signals

پرچم omit-user-bidding-signals شی userBiddingSignals را در محموله مزایده حذف می کند.

اگر پرچم تنظیم نشده باشد، مقدار userBiddingSignals تعریف شده در گروه علاقه در داخل generateBid() سرویس Bidding در دسترس خواهد بود.

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() در حال اجرا در Bidding Service در دسترس نیستند.

خریدار برای رسیدگی به اطلاعات آگهی از دست رفته، یک شناسه ( 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() ایجاد کرد.

اولویت های گروه علاقه مند را تعیین کنید

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

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

اموال	توضیحات
بردار اولویت	خریدار بردارها را به عنوان مقدار کلید `priorityVector` از سرویس K/V عرضه می کند.
سیگنال های اولویت دار	فروشنده سیگنال ها را با تنظیم `priority_signals` پیکربندی حراج تامین می کند
سیگنال های اولویت لغو می شوند	خریدار لغو را در قسمت `priority_signals_overrides` `PerBuyerConfig` در پیکربندی حراج ارائه می کند.

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

هر کلید در اشیاء بردار اولویت و سیگنال های اولویت در یکدیگر ضرب می شوند، سپس نتایج با هم جمع می شوند تا اولویت محاسبه شود. — **شکل 1** : محاسبه اولویت با استفاده از بردارهای خریدار و سیگنال های فروشنده

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

سیگنال	توضیحات
`deviceSignals.one`	مقدار همیشه 1 است و برای افزودن یک ثابت به محصول نقطه مفید است.
`deviceSignals.ageInMinutes`	این مقدار سن گروه مورد علاقه (زمان از زمان پیوستن آخرین گروه ذینفع) را به صورت یک عدد صحیح بین 0 تا 43200 در دقیقه توصیف می کند.
`deviceSignals.ageInMinutesMax60`	مقدار مشابه سیگنال `ageInMinutes` است، اما حداکثر در 60 است. اگر گروه بیش از 1 ساعت قدمت داشته باشد، 60 برگردانده می شود.
`deviceSignals.ageInHoursMax24`	این مقدار سن گروه مورد علاقه را بر حسب ساعت توصیف می‌کند که حداکثر 24 ساعت است. اگر گروه بیش از یک روز است، 24 برگردانده می شود.
`deviceSignals.ageInDaysMax30`	این مقدار سن گروه مورد علاقه را بر حسب روز توصیف می کند که حداکثر 30 روز است. اگر گروه بیش از 30 روز است، 30 برگردانده می شود.

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

سیگنال های مناقصه قابل اعتماد را تنظیم کنید

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

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

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

داده های حذف شده از گروه ذینفع را می توان به سرور مجموعه خریدار ارسال کرد. سرور مجموعه داده ها را به سرویس کلید/مقدار هل می دهد و در زمان بعدی مرورگر آن داده ها را از سرویس کلید/مقدار بارگیری می کند. — **شکل 2** : نمونه راه اندازی سیگنال های قابل اعتماد

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

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

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

وظایف `generateBid()`

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

سیگنال های مرورگر را بخوانید

شی browserSignals ارسال شده به فراخوانی B& 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
  ]
})

سپس رنگ مورد علاقه کاربر و اطلاعات محصول را می فرستیم تا در سرویس 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()`

از آنجایی که شناسه‌های گزارش‌دهی در محموله مزایده B&A گنجانده نشده‌اند، شناسه از طریق سیگنال‌های پیشنهادی قابل اعتماد برای generateBid() Bid در دسترس قرار می‌گیرد. زمانی که شناسه گزارشی مورد استفاده مشخص شد، شناسه گزارش انتخابی از 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 به جای buyerReportingId در buyerReportingSignals موجود است.

برای اطلاعات بیشتر به راهنمای Reporting ID مراجعه کنید.

مراحل بعدی

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

بیشتر بدانید

درباره تنظیمات حراج B&A در Chrome بیشتر بیاموزید
با دنبال کردن کد لبه تست محلی End-to-End با B&A با مخاطب محافظت شده آزمایش کنید.

سوالی دارید؟

اگر در مورد خدمات مزایده و مزایده سؤالی دارید، موضوعی را در مخزن خدمات B&A باز کنید .
اگر در مورد Privacy Sandbox به طور کلی سؤالی دارید، یک مشکل را در مخزن privacy-sandbox-dev-support باز کنید.