Запустите аукцион на основе браузера с одним продавцом

В этом документе вы найдете общий обзор проведения аукциона с данными Защищенной аудитории для одного продавца, который используется в текущей версии API Защищенной аудитории. Аукцион с одним продавцом может быть проведен как часть более сложного аукциона с участием нескольких продавцов. В этом случае аукцион с одним продавцом называется «аукционом компонентов», который может предоставлять кандидатов на рекламу на «аукцион верхнего уровня», в котором участвуют несколько продавцов.

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

Шесть этапов рекламного аукциона API Protected Audience API

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

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

Продавцы инициируют аукцион рекламы, оценивают рекламные объявления-кандидаты, используя пользовательскую логику, предоставляемую в виде функции scoreAd() , и несут ответственность за сообщение о результатах аукциона себе, а также победившему покупателю. Продавцы также могут обеспечивать соблюдение правил издателя и фильтровать качество рекламы с помощью функции scoreAd() .

Продавец может иметь в виду:

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

Предварительные условия для проведения аукциона

Продавцу необходимы две функции JavaScript, определенные для проведения аукциона:

  • scoreAd() , который оценивает кандидата на рекламу
  • reportResult() , который обрабатывает сообщение о результате аукциона самому продавцу.

Эти сценарии должны обслуживаться с одной конечной точки, принадлежащей продавцу.

scoreAd()

Продавцу необходимо определить функцию scoreAd() , которая обслуживается из принадлежащей ему конечной точки. Конечная точка указывается в конфигурации аукциона как decisionLogicUrl . Функция scoreAd() имеет следующую сигнатуру:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Параметры scoreAd() :

  • adMetaData — произвольные метаданные о рекламном объявлении, предоставленные покупателем. Это сериализуемый объект JSON, структуру которого продавцам и покупателям необходимо будет определить и согласовать.
  • bid , которая представляет собой числовое значение, представляющее ставку.
  • auctionConfig — конфигурация аукциона, используемая для проведения аукциона.
  • trustedScoringSignals — это сигналы, считываемые во время аукциона с сервера ключей/значений продавца. Платформа будет использовать renderUrl объявления-кандидата в качестве ключа для этого поиска.
  • browserSignals — объект, созданный браузером, включающий информацию, которую браузер знает и которую сценарий аукциона продавца может захотеть проверить.
  • directFromSellerSignals — это объект, который может содержать следующие поля: ** sellerSignals : аналогично auctionConfig.sellerSignals , но передается с использованием механизма directFromSellerSignals . ** auctionSignals : аналогично auctionConfig.auctionSignals , но передается с использованием механизма directFromSellerSignals .

Ниже приведен пример browserSignals . Обратите внимание, что renderUrl объявления-кандидата доступен через следующие сигналы: 

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Продавцу необходимо определить функцию reportResult() , которая обслуживается из принадлежащей ему конечной точки. Конечная точка указывается в конфигурации аукциона как decisionLogicUrl . Функция reportResult() имеет следующую сигнатуру:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Параметры reportResult() :

  • auctionConfig — конфигурация аукциона, используемая для проведения аукциона.
  • browserSignals — объект, созданный браузером, включающий информацию, которую браузер знает и которую сценарий аукциона продавца может захотеть проверить. Это тот же объект, который передается в функцию scoreAds() .

reportResult() возвращает signalsForWinner , который представляет собой произвольный объект JSON, который передается в функцию отчетности выигравшего покупателя. Сюда должна быть включена любая соответствующая информация, которую продавец может предоставить об аукционе, которую покупатель требует для отчетности.

Запустите аукцион API защищенной аудитории

Есть четыре основных шага, которые продавец должен предпринять для проведения аукциона. Обратите внимание, что эти шаги предполагают, что у продавца настроена конечная точка для возврата необходимого кода JavaScript, ранее упомянутого в этом руководстве.

  1. Настройте аукцион. Этот шаг включает в себя создание объекта auctionConfig . Это позволяет продавцу указать, какие покупатели должны участвовать в аукционе, а также подавать любые сигналы, которые могут иметь значение при формировании ставок или оценке рекламы.
  2. Запустите аукцион, вызвав navigator.runAdAuction() , передав конфигурацию, созданную на предыдущем шаге. Это запускает цепочку покупателей, генерирующих ставки, а затем подсчитывающих баллы. Конечным результатом этого шага является рекламный кандидат, который можно отобразить для отображения рекламы.
  3. Отобразите выигрышное объявление в огороженном фрейме или iframe.
  4. Сообщите о результате аукциона. Существует функция navigator.sendReportTo() , которая инициирует создание отчетов. Продавец всегда получит отчет о результатах аукциона. Отчет получит только покупатель, выигравший аукцион. При этом используется reportResult() продавца, описанный ранее в этом руководстве, для отправки отчета на его сервер.