Интегрируйтесь с B&A в качестве покупателя

Сервисы торгов и аукционов (B&A) — это набор сервисов для покупателей и продавцов рекламы, работающих в среде доверенного исполнения (TEE) для проведения аукциона с защищённой аудиторией (PA). В этом руководстве разработчика объясняется, как покупатель может интегрироваться с аукционом B&A PA для Chrome.

Обзор

Чтобы принять участие в аукционе защищенной аудитории с B&A Services, покупатель обновляет группу интересов (IG), чтобы оптимизировать полезную нагрузку для уменьшения задержки аукциона.

Покупателю необходимо выполнить следующие задачи по оптимизации полезной нагрузки:

• задачи joinAdInterestGroup()
  • Установить флаги запроса сервера
  • Установить идентификаторы отображения рекламы
  • Установить приоритеты группы интересов
  • Настройте надежные сигналы торгов
• задачи generateBid()
  • Чтение сигналов браузера
  • URL-адрес рендеринга возврата
  • Идентификатор отчета о возврате

Группа интересов 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 позволяет устанавливать флаги, сообщающие браузеру о необходимости исключить некоторые данные из полезной нагрузки аукциона 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, и вместо этого эти данные становятся доступными через использование службы 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() работающей в Bidding Service.

Для обработки отсутствующей информации о рекламе покупатель поддерживает идентификатор ( adRenderId и adComponentRenderId ), связанный с каждым объявлением в конфигурации группы интересов. Идентификатор должен представлять собой строку DOM длиной не более 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 и prioritySignals для определения приоритета. На следующей диаграмме приоритет рассчитывается по формуле (4 * 2) + (3 * -1) , что сокращается до 8 + -3 , поэтому приоритет этой группы интересов на момент аукциона равен 5 .

Также доступны дополнительные сигналы, которые можно использовать для определения приоритетов в B&A:

Чтобы узнать больше, посетите объяснительную страницу на GitHub .

Настройте надежные сигналы торгов

Поскольку некоторые данные будут исключены из полезной нагрузки аукциона B&A, вы можете использовать службу «ключ/значение» для предоставления исключенных данных в качестве надежных сигналов торгов для функции 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 . Обратите внимание, что 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 доступны следующие измененные или новые свойства:

Возвращает 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 .

Более подробную информацию можно узнать в руководстве по идентификатору отчетности .

Следующие шаги

Вам доступны следующие ресурсы:

Узнать больше

• Узнайте больше о конфигурациях аукциона B&A в Chrome
• Поэкспериментируйте с защищенной аудиторией с помощью B&A, следуя кодовой лаборатории «Локальное сквозное тестирование» .

Есть вопросы?

• Если у вас есть вопрос по услугам торгов и аукционов, откройте вопрос в репозитории услуг B&A .