Руководство для продавцов и покупателей по созданию отчетов об аукционах 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 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.
Что дальше?
Мы хотим пообщаться с вами, чтобы убедиться, что мы создаем API, который будет работать для всех.
Обсудить API
Как и другие API Privacy Sandbox, этот API документирован и обсуждается публично .
Экспериментируйте с API
Вы можете экспериментировать и участвовать в обсуждении API Protected Audience.