Отчет о результатах аукциона Protected Audience API

Руководство для продавцов и покупателей по созданию отчетов по аукционам с использованием API защищенной аудитории.

Данная статья представляет собой техническое руководство по созданию отчетов о выигрышах в аукционах с использованием API защищенной аудитории, как это используется в текущей версии экспериментального API защищенной аудитории.

Ознакомьтесь с руководством для разработчиков, чтобы узнать о полном жизненном цикле API защищенной аудитории, и обратитесь к пояснению к API защищенной аудитории для подробного обсуждения отчетности на уровне событий (временной) .

Не являетесь разработчиком? Ознакомьтесь с обзором API для защищенной аудитории .

Что сообщает API защищенной аудитории?

Доступны два отчета по API для защищенной аудитории:

  • Отчет продавца : Информирует продавца о победителе аукциона по объявлению.
  • Отчет покупателя : Доступен только покупателям, выигравшим аукцион, чтобы узнать, что они одержали победу.

В долгосрочной перспективе планируется разрешить браузеру сообщать результаты аукциона продавцу и покупателям с помощью API частной агрегации . В качестве временного механизма отчетности на уровне событий код, реализующий функцию reportResult() для продавца и reportWin() для победившего участника торгов, может вызывать функцию sendReportTo() . Эта функция принимает один аргумент: строку, представляющую URL-адрес, который загружается после завершения аукциона и содержит информацию об уровне события, подлежащую отчетности.

Функции API

Продавец: reportResult()

JavaScript-код продавца, предоставленный в decisionLogicUrl (который также предоставляет scoreAd() ), может включать функцию reportResult() для отображения результатов аукциона.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

В эту функцию передаются следующие аргументы:

auctionConfig

Объект конфигурации аукциона, переданный в функцию navigator.runAdAuction() .

browserSignals

Объект, созданный браузером и предоставляющий информацию об аукционе. Например:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

Возвращаемое значение этой функции используется в качестве аргумента sellerSignals для функции reportWin() победившего участника торгов.

Покупатель: reportWin()

JavaScript-код победившего участника торгов (который также предоставлял generateBid() ) может включать функцию reportWin() для сообщения о результатах аукциона.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

В эту функцию передаются следующие аргументы:

auctionSignals и perBuyerSignals

Для победившего участника торгов в функцию generateBid() передаются те же значения.

sellerSignals

Возвращаемое значение функции reportResult() предоставляет продавцу возможность передать информацию покупателю.

browserSignals

Объект, созданный браузером и предоставляющий информацию об аукционе. Например:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Временное внедрение системы отчетности

В Chrome временно доступны два способа отправки отчетов об аукционах:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Каждый из этих методов принимает один аргумент: URL-адрес, который нужно получить после завершения аукциона. Их можно вызывать несколько раз, как в scoreAd() , так и в generateBid() , с разными аргументами в виде URL-адресов.

Chrome отправляет отладочные отчеты о проигрыше/выигрыше только после завершения аукциона. Если аукцион отменяется (например, из-за нового элемента навигации), отчеты не генерируются.

Эти методы доступны по умолчанию в Chrome, если вы включите все API конфиденциальности рекламы в разделе chrome://settings/adPrivacy . Если вы используете Chrome с флагами командной строки для включения API защищенной аудитории, вам потребуется явно включить эти методы, добавив флаг BiddingAndScoringDebugReportingAPI . Если флаг не включен, методы все равно будут доступны, но ничего не будут делать.

Все ссылки на API защищенной аудитории

Справочные руководства по API доступны:

Объяснение API Protected Audience также содержит подробную информацию о поддержке функций и ограничениях.

Что дальше?

Мы хотим пообщаться с вами, чтобы убедиться, что мы создаем API, который будет работать для всех.

Обсудить API

Как и другие API Privacy Sandbox, этот API документирован и обсуждается публично .

Экспериментируйте с API

Вы можете экспериментировать и участвовать в обсуждении API Protected Audience.