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

Руководство по использованию API для продавцов и справочные материалы по аукциону рекламы с помощью API защищенной аудитории.

В этой статье вы найдете техническое описание аукциона рекламы, используемого в текущей версии экспериментального API защищенной аудитории.

Ознакомьтесь с руководством для разработчиков, чтобы узнать о полном жизненном цикле API защищенной аудитории, и обратитесь к пояснительной статье об API защищенной аудитории для более подробного обсуждения того, как продавцы проводят аукционы на своих устройствах .

Не являетесь разработчиком? Ознакомьтесь с обзором API для защищенной аудитории .

Что такое аукцион рекламы через API защищенной аудитории?

Аукцион рекламы с использованием API защищенной аудитории представляет собой набор небольших JavaScript-программ, которые браузер запускает на устройстве пользователя для выбора рекламы. Для обеспечения конфиденциальности весь код аукциона рекламы от продавца и покупателей выполняется в изолированных JavaScript- ворклетах , которые не могут взаимодействовать с внешним миром.

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

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

API защищенной аудитории может использоваться как самостоятельно, так и в сочетании с программными аукционами. В многопродавцовом программном аукционе:

  1. Пользователь посещает сайт-участник.
  2. Программный аукцион проводится другим продавцом для поиска контекстной рекламы на доступном рекламном месте.
  3. Аукцион по API защищенной аудитории запущен.
  4. scoreAd() сравнивает ставки покупателя с результатами первого аукциона.

Предложения, которые не могут превзойти предложенного победителя, отклоняются.

Кто управляет аукционом рекламы через API защищенной аудитории?

Существует несколько сторон, которые могут проводить аукционы по продаже рекламного пространства.

Например:

  • Издатель контента : действует от своего имени, размещая рекламный контент на своем веб-сайте.
  • Платформа со стороны предложения (SSP) : работа с издателем и предоставление других услуг.
  • Скрипт стороннего разработчика : созданный от имени издателя для обеспечения возможности участия в рекламных аукционах.

При использовании API защищенной аудитории у продавца три задачи:

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

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