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

Руководство для продавцов и покупателей по созданию отчетов об аукционах API Protected Audience.

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

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

Не разработчик? См. обзор API Protected Audience API .

Что сообщает API Protected Audience?

Доступны два отчета API Protected Audience:

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

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

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

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

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

后续操作

我们希望与您交流，确保我们构建适合所有人的 API。

讨论 API

与其他 Privacy Sandbox API 一样，此 API 也会记录在案并公开讨论。

使用 API 进行实验

您可以进行实验并参与有关 Protected Audience API 的对话。