Руководство для продавцов и покупателей по созданию отчетов по аукционам с использованием 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 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.