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

Руководство и справочные материалы по 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.
  1. Пользователь посещает сайт, на котором отображается реклама.
  2. Код продавца выполняет navigator.runAdAuction() . Здесь указывается, какое рекламное место продается и кто может делать ставки. Продавцы также должны включить скрипт, который оценивает каждую ставку, scoreAd() .
  3. Код приглашенного покупателя генерирует ставку, URL-адрес соответствующего рекламного объявления и другие данные. Сценарий назначения ставок может запрашивать данные в реальном времени, такие как оставшийся бюджет рекламной кампании, у службы «ключ-значение» покупателя.
  4. Код продавца оценивает каждую ставку и выбирает победителя. Эта логика использует значение ставки и другие данные, возвращающие желательность ставки. Объявления, которые не могут превзойти контекстного победителя, отклоняются. Продавец может использовать собственную службу «ключ/значение» для данных в реальном времени.
  5. Победившее объявление возвращается в виде непрозрачного значения, которое отображается в огороженной рамке . Ни продавец, ни издатель не смогут просмотреть это значение.
  6. О ходе аукциона сообщается продавцу и победившим покупателям.

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

API Protected Audience можно запускать отдельно или с помощью программных аукционов. В программном аукционе с несколькими продавцами:

  1. Пользователь посещает участвующий сайт.
  2. Другой продавец проводит программный аукцион, чтобы найти контекстное объявление для доступного рекламного места.
  3. Запущен аукцион Protected Audience API.
  4. 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() конкретного покупателя.
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 также содержит подробную информацию о поддержке функций и ограничениях.