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

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

Обзор

Для участия в аукционе с защищенной аудиторией, проводимом компанией B&A Services, покупатель обновляет группу интересов (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,
});

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

Обратите внимание, что URL-адреса 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 длиной не более 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 , связанный с рекламными объявлениями, становится доступен в generateBid() в методе prevWins.browserSignals .

Хотя renderURL не включается в полезную нагрузку запроса, возвращаемый функцией generateBid() URL рендеринга должен совпадать с 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 и связанные с ним значения отправляются на ваш сервер для загрузки в службу «Ключ/Значение». Позже, во время аукциона, браузер получает доверенные сигналы и делает их доступными в функции generateBid() покупателя.

При необходимости верните сигнал об обновлении информации от группы интересов из КВ.

Ключ updateIfOlderThanMs для доверенных сигналов используется для обновления группы интересов раньше обычного суточного интервала. Если группа интересов не была присоединена или обновлена ​​в течение времени, превышающего значение в миллисекундах, возвращаемое ключом updateIfOlderThanMs , группа интересов будет обновлена ​​с помощью механизма updateURL . Обратите внимание, что Chrome не будет обновлять группы интересов чаще, чем раз в 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 отсутствует в полезной нагрузке аукциона 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;
}

Если метод generateBid() не возвращает значение buyerReportingId , то вместо buyerReportingId в interestGroupName будет доступно значение buyerReportingSignals .

Для получения более подробной информации посетите руководство по идентификаторам отчетов .

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

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

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

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

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

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