Эта страница переведена с помощью Cloud Translation API.

Руководство для продавцов: проводите аукционы рекламы

Руководство и справочные материалы по 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 — На этой диаграмме показан каждый этап рекламного аукциона API Protected Audience.

Пользователь посещает сайт, на котором отображается реклама.
Код продавца выполняет navigator.runAdAuction() . Здесь указывается, какое рекламное место продается и кто может делать ставки. Продавцы также должны включить скрипт, который оценивает каждую ставку, scoreAd() .
Примечание. Перед началом аукциона продавец находит лучшее контекстное объявление для доступного рекламного места.
Код приглашенного покупателя генерирует ставку, URL-адрес соответствующего рекламного объявления и другие данные. Сценарий назначения ставок может запрашивать данные в реальном времени, такие как оставшийся бюджет рекламной кампании, у службы «ключ-значение» покупателя.
Код продавца оценивает каждую ставку и выбирает победителя. Эта логика использует значение ставки и другие данные, возвращающие желательность ставки. Объявления, которые не могут превзойти контекстного победителя, отклоняются. Продавец может использовать собственную службу «ключ/значение» для данных в реальном времени.
Победившее объявление возвращается в виде непрозрачного значения, которое отображается в огороженной рамке . Ни продавец, ни издатель не смогут просмотреть это значение.
О ходе аукциона сообщается продавцу и победившим покупателям.
Примечание. reportResult() продавца и reportWin() покупателя могут включать вызов sendReportTo() . Это доступно временно , пока не станет доступна сводная отчетность с помощью Private Aggregation .

Когда состоится аукцион?

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> ), который представляет результат аукциона объявлений. Это может быть декодировано браузером только при передаче в изолированный фрейм для рендеринга: страница издателя не может проверить выигравшее объявление.

Примечание. Источник сценария с joinAdInterestGroup() должен совпадать с источником владельца группы интересов, поэтому joinAdInterestGroup() необходимо будет вызывать из iframe (например, из DSP), если только источник владельца группы интересов не совпадает с источником. текущего документа (например, веб-сайт со своими группами по интересам). runAdAuction не предъявляет таких же требований, поэтому использование тега <script> , вероятно, гораздо более эффективно, чем iframe с перекрестным происхождением.

Сценарий decisionLogicUrl по одному рассматривает каждое отдельное объявление вместе со связанной с ним ставкой и метаданными, а затем присваивает ему числовой показатель желательности.

Свойства `auctionConfig`

Примечание. additionalBids не поддерживаются в текущей реализации API Protected Audience. Для получения дополнительной информации прочтите раздел «Участники аукциона» в объяснении API Protected Audience.

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() конкретного покупателя.

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 также содержит подробную информацию о поддержке функций и ограничениях.

Руководство для продавцов: проводите аукционы рекламы

Что такое аукцион объявлений Protected Audience API?

Когда состоится аукцион?

Кто проводит аукцион объявлений Protected Audience API?

API-функции

runAdAuction()

Свойства auctionConfig

decisionLogicUrl

browserSignals

scoreAd()

Часто задаваемые вопросы

Как определяется победитель аукциона и кто его выбирает?

Все ссылки на API защищенной аудитории

`runAdAuction()`

Свойства `auctionConfig`

`decisionLogicUrl`

`browserSignals`

`scoreAd()`