Узнайте, как настроить аукцион API защищенной аудитории.
Аукционы на устройствах, проводимые продавцами
Аукцион Защищенной аудитории на устройстве проводится на сайте, продающем рекламные места, и мы называем сторону, проводящую аукцион, продавцом. Многие стороны могут выступать в роли продавцов: сайт может проводить собственный рекламный аукцион или может включать сторонний скрипт для проведения аукциона или может использовать SSP, который сочетает проведение аукциона на устройстве с другой рекламой на стороне сервера. аукционная деятельность. Продавцы выполняют три основные задачи на аукционе рекламы на устройстве:
- Продавцы решают (а) какие покупатели могут участвовать и (б) какие предложения от групп интересов этих покупателей имеют право участвовать в аукционе. Это позволяет продавцу обеспечить соблюдение правил сайта относительно того, какие объявления разрешено показывать на странице.
- Продавцы несут ответственность за бизнес-логику аукциона: код JavaScript, который учитывает цену и метаданные каждой ставки и вычисляет оценку «желательности». Ставка с наивысшим баллом желательности выигрывает аукцион.
- Продавцы предоставляют отчетность о результатах аукциона, включая информацию о клиринговой цене и любых других выплатах. Выигравшие и проигравшие покупатели также могут составлять собственные отчеты.
В этом документе объясняется, как настроить и запустить аукцион на устройстве.
Настройка аукциона объявлений API Protected Audience
Чтобы запустить аукцион объявлений API Protected Audience, первым делом необходимо настроить аукцион. Это делается путем создания объекта auctionConfig . Вот пример одной из таких конфигураций:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
Свойства AuctionConfig
Обязательные свойства
Единственные необходимые свойства для auctionConfigs — это seller , decisionLogicUrl и interestGroupBuyers .
| Свойство | Пример | Роль |
|---|---|---|
| продавец | https://seller.пример | Происхождение продавца. |
| решениеLogicUrl | https://seller.example/decision-logic.js | URL-адрес для работы с логикой принятия решений на JavaScript на аукционе. Это поле должно иметь то же происхождение, что и поле продавца. |
| интересГруппаПокупатели | [https://buyer-1.example, https://покупатель-2.пример, ...] | Происхождение всех владельцев групп по интересам, которых попросили принять участие в аукционе |
Дополнительные свойства
Остальные свойства auctionConfigs являются необязательными.
| Свойство | Пример | Роль |
|---|---|---|
| доверенныйScoringSignalsUrl | https://seller.example/scoring-signals | URL-адрес сервера ключей/значений продавца. Этот запрос будет запрошен в процессе оценки объявления с использованием URL-адреса отображения креатива в качестве ключа. Это поле должно иметь то же происхождение, что и поле продавца. |
| аукционСигналы | {"category":"новости"} | Сериализуемый объект JSON, представляющий сигналы, доступные всем покупателям и продавцам, участвующим в аукционе. |
| продавецСигналы | {...} | Сериализуемый объект JSON, представляющий сигналы, доступные только продавцам. |
| perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } | Сигналы доступны конкретному покупателю. Сигналы могут исходить как от продавцов, так и от самих покупателей. |
| perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, | Максимальное время выполнения скриптаgenerateBid() конкретного покупателя в миллисекундах. Подстановочный знак будет применяться к каждому покупателю, для которого не определен конкретный тайм-аут. |
| продавецТаймаут | 100 | Максимальное время выполнения скрипта ScoreAd() продавца в миллисекундах. |
| КомпонентАукционы | [{продавец: https://www.some-other-ssp.com, DecisionLogicUrl: ..., ...}, ...] | Дополнительные настройки для аукционов компонентов. |
| разрешитьToConfig | правда|ложь | Логическое значение, указывающее обещанию, возвращенному из runAdAuction(), преобразоваться в FencedFrameConfig, если оно истинно (для использования в <fencedframe>), или в непрозрачный URL-адрес urn:uuid, если оно ложно (для использования в <iframe>). По умолчанию ложь. |
Предоставляйте сигналы асинхронно
Значения некоторых сигналов (настроенных полями auctionSignals , sellerSignals , perBuyerSignals и perBuyerTimeouts ) при желании могут быть предоставлены не как конкретные значения, а как Promises . Это позволяет некоторым частям аукциона, таким как загрузка сценариев и доверенных сигналов, а также запуск изолированных рабочих процессов, перекрывать вычисление (или извлечение по сети) этих значений. Сценарии рабочих листов будут видеть только разрешенные значения; если какое-либо такое обещание будет отклонено, аукцион будет прерван, если только он уже не провалился или не был прерван другими способами.
Настройка аукциона с несколькими продавцами
В некоторых случаях в аукционе могут принять участие несколько продавцов, при этом победители отдельных аукционов передаются на другой аукцион, проводимый другим продавцом. Эти отдельные аукционы, которые пропускаются, называются компонентными аукционами. Чтобы облегчить эти аукционы компонентов, объект componentAuctions может содержать дополнительные конфигурации аукциона для аукциона компонентов каждого продавца. Победившая ставка каждого из этих составных аукционов будет передана на аукцион «верхнего уровня», который принимает окончательное решение по итогам аукциона. auctionConfig аукционов компонентов не может иметь собственных componentAuctions . Если componentAuctions не пуст, то interestGroupBuyers должен быть пустым. То есть для любого конкретного аукциона Защищенной аудитории либо есть один продавец и нет аукционов компонентов, либо все ставки поступают с аукционов компонентов, и аукцион верхнего уровня может выбирать только среди победителей аукционов компонентов.
Запустить аукцион
Продавец отправляет запрос браузеру пользователя на начало аукциона объявлений, вызывая navigator.runAdAuction() .
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
Вызов runAdAuction() возвращает обещание, которое преобразуется в объявление. Никакой код на странице издателя не может проверить выигравшее объявление или иным образом узнать о его содержании из результата runAdAuction() . Если в AuctionConfig для resolveToConfig установлено значение true, возвращается объект FencedFrameConfig , который можно отобразить только в изолированном фрейме. Если для флага установлено значение false, то возвращается непрозрачный URN, который можно отобразить в iframe. Возможно, runAdAuction возвращает нулевое значение, указывающее, что объявление не было выбрано. В этом случае продавец может выбрать показ контекстно-ориентированной рекламы.