Руководство и справочные материалы по API продавца для аукциона объявлений API защищенной аудитории.
В этой статье вы найдете техническое описание аукциона рекламы, используемого в текущей версии экспериментального API Protected Audience.
Прочтите руководство для разработчиков по полному жизненному циклу API Protected Audience и обратитесь к объяснению API Protected Audience для подробного обсуждения того, как продавцы проводят аукционы на устройствах .
Не разработчик? См. обзор API Protected Audience .
Что такое аукцион объявлений Protected Audience API?
Аукцион объявлений API Protected Audience — это набор небольших программ JavaScript, которые браузер запускает на устройстве пользователя для выбора объявления. Чтобы сохранить конфиденциальность, весь код аукциона рекламы от продавцов и покупателей выполняется в изолированных JavaScript- программах , которые не могут взаимодействовать с внешним миром.
![Шесть этапов рекламного аукциона API Protected Audience API](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=9&hl=ru)
- Пользователь посещает сайт, на котором отображается реклама.
- Код продавца выполняет
navigator.runAdAuction()
. Здесь указывается, какое рекламное место продается и кто может делать ставки. Продавцы также должны включить скрипт, который оценивает каждую ставку,scoreAd()
. - Код приглашенного покупателя генерирует ставку, URL-адрес соответствующего рекламного объявления и другие данные. Сценарий назначения ставок может запрашивать данные в реальном времени, такие как оставшийся бюджет рекламной кампании, у службы «ключ-значение» покупателя.
- Код продавца оценивает каждую ставку и выбирает победителя. Эта логика использует значение ставки и другие данные, возвращающие желательность ставки. Объявления, которые не могут превзойти контекстного победителя, отклоняются. Продавец может использовать собственную службу «ключ/значение» для данных в реальном времени.
- Победившее объявление возвращается в виде непрозрачного значения, которое отображается в огороженной рамке . Ни продавец, ни издатель не смогут просмотреть это значение.
- О ходе аукциона сообщается продавцу и победившим покупателям.
Когда состоится аукцион?
API Protected Audience можно запускать отдельно или с помощью программных аукционов. В программном аукционе с несколькими продавцами:
- Пользователь посещает участвующий сайт.
- Другой продавец проводит программный аукцион, чтобы найти контекстное объявление для доступного рекламного места.
- Запущен аукцион Protected Audience API.
-
scoreAd()
сравнивает ставки покупателя с результатами первого аукциона.
Ставки, которые не могут превзойти контекстного победителя, отклоняются.
Кто проводит аукцион объявлений Protected Audience API?
Есть несколько сторон, которые могут провести аукцион по продаже рекламного места.
Например:
- Издатель контента : действует от своего имени и размещает рекламный контент на своем веб-сайте.
- Платформа предложения (SSP) : работа с издателем и предоставление других услуг.
- Сторонний скрипт : действует от имени издателя, чтобы обеспечить участие в рекламных аукционах.
С API Protected Audience у продавца есть три задачи:
- Обеспечьте соблюдение правил издателя: какие покупатели и какие ставки имеют право на участие.
- Запуск логики аукциона: JavaScript запускается в рабочих модулях для расчета показателя желательности для каждой ставки.
- Сообщите о результатах аукциона.
Эти задания выполняются программно, в коде, предоставленном продавцом, когда он инициирует аукцион рекламы, вызывая функцию JavaScript navigator.runAdAuction()
.
API-функции
runAdAuction()
Продавец отправляет запрос браузеру пользователя на начало аукциона объявлений, вызывая navigator.runAdAuction()
.
Например:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
возвращает обещание, которое преобразуется в URN ( urn:uuid:<something>
), который представляет результат аукциона объявлений. Это может быть декодировано браузером только при передаче в изолированный фрейм для рендеринга: страница издателя не может проверить выигравшее объявление.
Сценарий decisionLogicUrl
по одному рассматривает каждое отдельное объявление вместе со связанной с ним ставкой и метаданными, а затем присваивает ему числовой показатель желательности.
Свойства auctionConfig
-
seller
- Необходимый
- Пример:
'https://ssp.example'
- Роль: Происхождение продавца.
-
decisionLogicUrl
- Необходимый
- Пример:
'https://ssp.example/auction-decision-logic.js'
- Роль: URL-адрес JavaScript-файла аукциона.
-
trustedScoringSignalsUrl
- Необязательный
- Пример:
'https://ssp.example/scoring-signals'
- Роль: URL доверенного сервера продавца.
-
interestGroupBuyers
- Необходимый
- Пример:
['https://dsp.example', 'https://buyer2.example', ...]
- Роль: Происхождение всех владельцев групп по интересам, которых попросили принять участие в аукционе.
- Примечания: Продавец может указать
interestGroupBuyers:
чтобы разрешить участие в торгах всем группам интересов. Затем объявления принимаются или отклоняются на основе критериев, отличных от включения владельца группы по интересам. Например, продавец может проверить рекламные объявления на предмет соответствия его политике. -
auctionSignals
- Необязательный
- Пример:
{...}
- Роль: информация о продавце о контексте страницы, типе аукциона и т. д.
-
sellerSignals
- Необязательный
- Пример:
{...}
- Роль: информация на основе настроек издателя, запроса контекстной рекламы и т. д.
-
sellerTimeout
- Необязательный
- Пример:
100
- Роль: максимальное время выполнения (мс) сценария
scoreAd()
продавца. -
perBuyerSignals
- Необязательный
- Пример:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Роль: Контекстные сигналы о странице для каждого конкретного покупателя, с его сервера.
-
perBuyerTimeouts
- Необязательный
- Пример:
50
- Роль: максимальное время выполнения (мс) скриптовgenerateBid
generateBid()
конкретного покупателя. -
componentAuctions
- Необязательный
- Пример:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Роль: Дополнительные настройки для аукционов компонентов .
decisionLogicUrl
decisionLogicUrl
— это свойство объекта конфигурации аукциона, передаваемое в runAdAuction()
. Этот URL-адрес должен включать скрипт для функции scoreAd()
. Эта логика запускается один раз для каждого объявления, чтобы определить его желательность.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
— это объект, созданный браузером, включающий информацию, известную браузеру и которую сценарий аукциона продавца может захотеть проверить:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Перед началом аукциона продавец находит лучшее контекстное объявление для доступного рекламного места. Часть логики scoreAd()
отклоняет любое объявление, которое не может превзойти контекстное победившее объявление.
scoreAd()
scoreAd()
принимает следующие аргументы:
Аргумент | Роль |
---|---|
adMetadata | Произвольные метаданные, предоставленные покупателем. |
auctionConfig | Объект конфигурации аукциона, переданный в navigator.runAdAuction() . |
bid | Числовое значение ставки. |
trustedScoringSignals | Значения, полученные во время аукциона с доверенного сервера продавца, отражают мнение продавца об объявлении. |
Часто задаваемые вопросы
Как определяется победитель аукциона и кто его выбирает?
Продавец предоставляет логику оценки для определения оценки желательности каждого объявления, а браузер выбирает наивысший балл в качестве объявления-победителя.
Продавец включает логику в функцию scoreAd()
, а браузер выполняет эту функцию в ворлете, который имеет ограниченную связь с внешним кодом. Сам браузер рекламу не забивает. Браузер несет исключительную ответственность за выполнение логики оценки и выбор ставки с наивысшим баллом.
Все ссылки на API защищенной аудитории
Справочные руководства по API доступны:
- Руководство разработчика по API Protected Audience .
- Руководство для покупателей рекламы по группам интересов защищенной аудитории и формированию ставок .
- Руководство для продавцов рекламы по рекламным аукционам для защищенной аудитории.
- Руководство по сообщению о результатах аукциона
- Рекомендации по устранению задержки на аукционе объявлений для защищенной аудитории
- Устранение неполадок с защищенной аудиторией
Объяснение API Protected Audience также содержит подробную информацию о поддержке функций и ограничениях.