Эта страница переведена с помощью Cloud Translation API.

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

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

Обзор

Чтобы принять участие в аукционе защищенной аудитории с помощью B&A Services, покупатель обновляет группу интересов (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.
`auctionServerRequestFlags`	Использовал	Не используется	Нет
`userBiddingSignals`	Не рекомендуется	Использовал	Нет, если установлен флаг `omit-user-bidding-signals`
`adRenderId` в `ads` и `adComponents`	Использовал	Не используется	Если установлен флаг `omit-ads` , `adRenderId` в `ads` доступен только в файле `browserSignals.prevWins` полезных данных. `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.
Идентификаторы отчетов определены в B&A IG, но не включены в полезные данные аукциона B&A. Идентификатор отчета, возвращаемый generateBid() позже во время аукциона, должен соответствовать URL-адресу рендеринга, определенному в IG.
ad.metadata и идентификаторы отчетов не включаются в полезную нагрузку аукциона B&A, вместо этого эти данные становятся доступными посредством использования службы доверенных ключей/значений.

Обратите внимание, что renderURL и идентификаторы отчетов в ads по-прежнему определяются в конфигурации группы по интересам, хотя они не включаются в полезную нагрузку запроса аукциона, поскольку браузер проверяет, соответствуют ли URL-адрес рендеринга и идентификаторы отчетов, возвращаемые generateBid() службы назначения ставок, значениям, определенным в группе интересов.

задачи `joinAdInterestGroup()`

Для вызова joinAdInterestGroup() необходимо выполнить следующие задачи.

Установить флаги запроса сервера

Поле auctionServerRequestFlags конфигурации joinAdInterestGroup() принимает следующие флаги:

Флаг Описание

omit-user-bidding-signals

Флаг omit-user-bidding-signals исключает объект userBiddingSignals из полезных данных аукциона.

Если флаг не установлен, значение userBiddingSignals определенное в группе интересов, станет доступно внутри generateBid() службы назначения ставок.

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() , работающей в службе назначения ставок.

Чтобы обрабатывать недостающую информацию о рекламе, покупатель сохраняет идентификатор ( 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 позволяет покупателям расставлять приоритеты по группам интересов. Если достигнут предел размера полезных данных для каждого покупателя, установленный продавцом, значения приоритета группы интересов используются для удаления групп интересов с более низким приоритетом для одного покупателя, когда для продавца создаются полезные данные аукциона 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 до 43 200.
`deviceSignals.ageInMinutesMax60`	Значение соответствует сигналу `ageInMinutes` , но его максимальное значение равно 60. Если возраст группы превышает 1 час, возвращается 60.
`deviceSignals.ageInHoursMax24`	Значение описывает возраст группы интересов в часах, максимум 24 часа. Если группе больше суток, возвращается 24.
`deviceSignals.ageInDaysMax30`	Значение описывает возраст группы интересов в днях, максимум 30 дней. Если группе больше 30 дней, то возвращается 30.

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

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

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

Следующие пропущенные данные могут быть предоставлены Службой К/В:

userBiddingSignals если используется покупателем.
metadata связанные с каждым объявлением
adRenderId связанный с каждым объявлением
Идентификатор отчета

Пропущенные данные из группы интересов могут быть отправлены на сервер сбора данных покупателя. Сервер сбора передает данные в службу «ключ-значение», а позже браузер загружает эти данные из службы «ключ-значение». — **Рисунок 2.** Пример настройки доверенных сигналов.

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

При необходимости вернуть сигнал обновления группы интересов от 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
  ]
})

Затем мы отправляем любимый цвет пользователя и информацию о продукте для загрузки в службу ключей/значений:

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 Services .
Если у вас есть вопросы о Privacy Sandbox в целом, откройте вопрос в репозитории Privacy-Sandbox-dev-support.