Отчет о результатах аукциона 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-интерфейсов Private Aggregation 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 reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.