Инструкция для подключения монетизаторов к Yandex Header Bidding

Header Bidding — это programmatic-технология, которая при загрузке страницы сайта пользователем позволяет опросить несколько подключенных монетизаторов и выбрать среди них предложение с максимальной ставкой.

Библиотека Header Bidding не входит в коды вставки Adfox, а скачивается отдельно. Она не является открытым кодом. Добавление новых монетизаторов, взаимодействие с уже подключенными и все работы над библиотекой проводит Яндекс.

Описание процесса

Библиотека header-bidding.js отправляет со страницы POST-запрос, содержащий массив объектов places. В массиве описаны параметры всех баннерных мест, по которым запрашиваются ставки и креативы.
Монетизатор посылает ответ с кодом 200, содержащий массив bids со ставками и креативами по тем баннерным местам, на которых он желает показать рекламу. При этом:
- Ставки от монетизаторов содержатся в одном ответе.
- Креативы присылаются только на те места, по которым указаны ставки.
- Если монетизатор не подобрал рекламу ни по одному рекламному месту, отправляется пустой массив.
- Все обязательные поля каждого объекта bids из массива bids заполнены. Если хотя бы одно из обязательных полей не заполнено, ставка объявляется невалидной и исключается из аукциона.
- Win-notice и lose-notice не поддерживаются.
- Должны быть проставлены заголовки Access-Control-Allow-Origin с приходящим origin, а также Access-Control-Allow-Credentials: true.
Креативы передаются в параметре displayUrl или displayCode в зависимости от типа содержимого. При этом:
- HTML-креатив передается HTML-строкой в displayCode или ссылкой на HTML-файл в displayUrl.
- JavaScript-креатив передается JavaScript-строкой в displayCode или ссылкой на JavaScript-файл в displayUrl. JavaScript должен выполняться асинхронно.
- Видеореклама должна соответствовать спецификации IAB VAST 2.0.
- Для VAST используется кодировка modified Base64 for URL, где + и / стандартного Base64 заменяются на - и _ соответственно.
- Yandex Header Bidding поддерживает максимум три редиректа внутри Wrapper.

Подключение собственной биддинг-платформы

Требования к монетизатору

поддержка CORS;
поддержка HTTPS.

Общий формат запроса

{
  "places": [
  {
    "id": (string),
    "placementId": (string),
    "codeType": (string),
    "sizes": [array[array(int)]]
  }],
  "settings":
  {
    "currency": (string),
    "windowSize":
    {
     "width": (int),
     "height": (int)
    }
  }
}

Параметры запроса

Request object

Параметр	Описание	Обязательный
`places`	Объект, содержащий информацию о запрашиваемых рекламных местах.	Да
`settings`	Объект, содержащий дополнительную информацию.	Да

places

Параметр	Описание	Обязательный
`id`	ID контейнера в интерфейсе Adfox.	Да
`placementId`	ID площадки на стороне монетизатора.	Да
`sizes`	Массив массивов с ожидаемыми размерами баннера. Например: `[[300, 250]]` или `[[300, 250], [640, 480]]`. Размеры передаются только для `codeType: banner` и `combo`.	Нет
`targetRef`	Адрес страницы, с которой получен запрос рекламы.	Да
`codeType`	Формат запрашиваемой рекламы. Более подробная информация в блоке codeType.	Нет
`{additional_field}`	При необходимости по договоренности с монетизатором владелец сайта может использовать кастомные поля в конфиге Header Bidding на странице. Указанные поля будут переданы в запросе в корне поля `places`.	Нет

settings object

Параметр	Описание	Обязательный
`currency`	Значение валюты, в которой необходимо вернуть ставку в ответе. Допустимые валюты: RUB, USD, EUR, CHF, KZT, BYN, UAH.	Да
`windowSize`	Объект, содержащий информацию о размерах окна.	Да

settings.windowSize object

Параметр	Описание	Обязательный
`width`	Ширина окна, полученная методом `window.innerWidth`.	Да
`height`	Высота экрана, полученная методом `window.innerHeight`.	Да

Общий формат ответа

{
  "bids": [
  {
    "displayUrl": (string),
    "displayCode": (string),
    "id": (string),
    "cpm": (float),
    "currency": (string),
    "codeType": (string),
    "placementId": (string),
    "size":
    {
     "width": (int),
     "height": (int)
    }
  }]
}

Параметры ответа

Response object

Параметр	Описание	Обязательный
`bids`	Массив, содержащий информацию о ставках и креативах.	Да

bid object

Параметр	Описание	Обязательный
`id`	ID контейнера Аdfox из запроса.	Да
`displayUrl`	Ссылка на HTML-креатив, JS-код или VAST XML. В ответе допустимо присутствие `displayCode` или `displayUrl`.	Да
`displayCode`	Строка с HTML-креативом, JS-кодом или VAST XML в base64 (только для VAST). В ответе допустимо присутствие `displayCode` или`displayUrl`.	Да
`cpm`	Ставка в виде дробного числа больше нуля. Поддерживается до трех знаков включительно после запятой, при превышении количества знаков значение обрезается в меньшую сторону.	Да
`codeType`	Формат отдаваемой рекламы. Более подробная информация в блоке codeType.	Да
`placementId`	ID площадки на стороне монетизатора.	Да
`currency`	Значение валюты ставки в ответе. Допустимые валюты: RUB, USD, EUR, CHF, KZT, BYN, UAH.	Да
`size`	Объект, содержащий информацию о размерах креатива. Размеры передаются только для `codetype: banner` и `combo`.	Да
`disableFullscreen`	`disableFullscreen: true` отключает отрисовку подложки для полноэкранного баннера на стороне кода Adfox. Если монетизатор самостоятельно отрисует подложку, она отобразится на баннере. Подробнее о настройке полноэкранного баннера читайте в разделе Возможности кодов вставки.	Нет

size object

Параметр	Описание	Обязательный
`width`	Ширина креатива в пикселях.	Да
`height`	Высота креатива в пикселях.	Да

codeType

Опционально. При отсутствии в запросе поля codeType по умолчанию подразумевается запрос формата Banner.

Возможные значения:

Запрос	Ответ
Отсутствует `codeType`	Допустимы `codeType: html` или `js` (формат Banner).
`codeType: inpage`	`codeType: inpage` (формат Video).
`preroll`, `midroll` или `postroll`	Должен быть тот же `codeType`, что и в запросе (формат InStream).
`codeType: combo`	Допустимы: `codeType: html` или `js` (формат Banner); `inpage` (формат Video).

Формат ответа, когда не удалось подобрать рекламу

{
  "bids": []
}

Формат ответа, когда монетизатор возвращает информацию об ошибке

{
  "error":
  {
    "code": string,
    "message": string
  }
}

Запрос и ответ по нескольким баннерным местам

В этом примере Яндекс в массиве places отправляет информацию по трем баннерным местам, а монетизатор отказывается от ставки по одному из них.

Запрос

Ответ

curl 'https://bidder.com/bidder/adfox/bids'
-H 'pragma: no-cache'
-H 'cache-control: no-cache'
-H 'origin: https://www.site.ru'
-H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'content-type: text/plain'
-H 'accept: */*'
-H 'sec-fetch-site: cross-site'
-H 'sec-fetch-mode: cors'
-H 'referer: https://www.site.ru/'
-H 'accept-encoding: gzip, deflate, br'
-H 'accept-language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'
--data-binary
'
{
  "places": [
  {
    "id": "adfox_1481556385598437",
    "placementId": "75d5e9c8ccb72a90cad8",
    "sizes": [
      [970, 250]
    ]
  },
  {
    "id": "adfox_1481556257759831",
    "placementId": "2e9e0cf51bdd0cced4gg",
    "sizes": [
      [728, 90]
    ]
  },
  {
    "id": "adfox_14817108392655",
    "placementId": "cced462eeafdb72e1026",
    "sizes": [
      [728, 90]
    ]
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 1920,
      "height": 445
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayCode": "<iframe src='https://bidder.com/65236tgejwhr'></iframe>",
    "id": "adfox_1481556385598437",
    "cpm": 13.567,
    "currency": "RUB",
    "codeType": "html",
    "placementId": "75d5e9c8ccb72a90cad8",
    "size":
    {
      "width": 970,
      "height": 250
    }
  },
  {
    "displayCode": "<iframe src='https://bidder.com/65256237tgrjwhr'></iframe>",
    "id": "adfox_14817108392655",
    "cpm": 1.611,
    "currency": "RUB",
    "codeType": "html",
    "placementId": "cced462eeafdb72e1026",
    "size":
    {
      "width": 728,
      "height": 90
    }
  }]
}

Запрос и ответ в зависимости от формата рекламы

Формат Banner позволяет показывать рекламные объявления в виде баннеров, которые могут занимать часть экрана.

Запрос

Ответ

curl 'https://bidder.com/bidder/adfox/bids'
-H 'pragma: no-cache'
-H 'cache-control: no-cache'
-H 'origin: https://www.site.ru'
-H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.3
6 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'content-type: text/plain'
-H 'accept: */*'
-H 'sec-fetch-site: cross-site'
-H 'sec-fetch-mode: cors'
-H 'referer: https://www.site.ru/'
-H 'accept-encoding: gzip, deflate, br'
-H 'accept-language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'
--data-binary
'
{
  "places": [
    {
      "id": "adfox_1481556385598437",
      "placementId": "75d5e9c8ccb72a90cad8",
      "sizes": [
        [
          970,
          250
        ]
      ]
    }
  ],
  "settings": {
    "currency": "RUB",
    "windowSize": {
      "width": 1920,
      "height": 445
    }
  }
}
'
--compressed

{
  "bids": [
    {
      "displayCode": "<iframe src='https://bidder.com/65236tgejwhr'></iframe>",
      "id": "adfox_1481556385598437",
      "cpm": 13.567,
      "currency": "RUB",
      "codeType": "html",
      "placementId": "75d5e9c8ccb72a90cad8",
      "size": {
        "width": 970,
        "height": 250
      }
    }
  ]
}

Fullscreen

Формат Fullscreen содержит рекламные объявления, которые отображаются на весь экран устройства.

Ссылка на код JavaScript

"codeType": "js" в ответе для формата Fullscreen является обязательным. В контейнер выгружается тег <script> со значением атрибута src из параметра displayUrl. Размеры в ответе при этом должны быть следующие:

"size":
{
  "width": -1,
  "height": -1
}

Запрос

Ответ

curl 'https://banner.bidder.ru/bidder/request'
-H 'Connection: keep-alive'
-H 'Pragma: no-cache'
-H 'Cache-Control: no-cache'
-H 'Origin: https://banners.adfox.ru'
-H 'User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 10_2_1 like Mac OS X) AppleWebKit/602.4.6
(KHTML, like Gecko) Version/10.0 Mobile/14D27 Safari/602.1'
-H 'Content-Type: text/plain'
-H 'Accept: */*'
-H 'Sec-Fetch-Site: cross-site'
-H 'Sec-Fetch-Mode: cors'
-H 'Referer: https://banners.adfox.ru/191126/adfox/776731/bidder.html'
-H 'Accept-Encoding: gzip, deflate, br'
-H 'Accept-Language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'
--data-binary
'
{
  "places": [
  {
    "id": "adfox_157478164702549105",
    "placementId": "2362",
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 980,
      "height": 1743
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayUrl": "\/\/banner.bidder.ru\/bidder\/display?dbid=2&vbid=435797651",
    "id": "adfox_157478164702549105",
    "cpm": 1,
    "currency": "RUB",
    "codeType": "js",
    "placementId": "2362",
    "size":
    {
      "width": -1,
      "height": -1
    }
  }]
}

InPage

Формат InPage позволяет показывать видеорекламу на сайтах посреди контента.

VAST XML будет проигран в видеоплеере Яндекса.

Есть два варианта:

передавать base64 encoded VAST XML в параметре displayCode;
передавать ссылку на VAST XML в параметре displayUrl.

Запрос

Ответ

curl 'https://exchange.bidder.com/ssp/adfox'
-H 'Connection: keep-alive'
-H 'Pragma: no-cache'
-H 'Cache-Control: no-cache'
-H 'Origin: https://banners.adfox.ru'
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'Content-Type: text/plain'
-H 'Accept: */*'
-H 'Sec-Fetch-Site: cross-site'
-H 'Sec-Fetch-Mode: cors'
-H 'Referer: https://banners.adfox.ru/191126/adfox/776727/bidderinpage.html'
-H 'Accept-Encoding: gzip, deflate, br'
-H 'Accept-Language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'
--data-binary
'
{
  "places": [
  {
    "id": "adfox_15747754996035865",
    "placementId": "296669",
    "codeType": "inpage"
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 980,
      "height": 1743
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayCode":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48VkFTVCB2ZXJzaW9uPSIyLjAiPjwv
VkFTVD4=",
    "id": "adfox_15747754996035865",
    "cpm": 150,
    "currency": "RUB",
    "codeType": "inpage",
    "placementId": "296669"
  }]
}

InStream

Формат InStream позволяет показывать видеорекламу (pre-roll, pause-roll, post-roll, mid-roll) в плеере с собственным видеоконтентом.

Есть два варианта:

передавать base64 (URL safe) encoded VAST XML в параметре displayCode;
передавать ссылку на VAST XML в параметре displayUrl.

В теле запроса к монетизатору приходит adBreakType в поле codeType:

preroll;
midrol;
postroll.

Base64 (URL safe) encoded VAST XML

Запрос

Ответ

curl 'https://exchange.bidder.com/ssp/adfox'
-H 'Connection: keep-alive'
-H 'Pragma: no-cache'
-H 'Cache-Control: no-cache'
-H 'Origin: https://sites.help.adfox.ru'
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'Content-Type: text/plain'
-H 'Accept: */*'
-H 'Sec-Fetch-Site: cross-site'
-H 'Sec-Fetch-Mode: cors'
-H 'Referer: https://sites.help.adfox.ru/hb/HB_inpage.html'
-H 'Accept-Encoding: gzip, deflate, br'
-H 'Accept-Language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'
--data-binary
'
{
  "places": [
  {
    "id": "adfox_156536764866112926",
    "placementId": "296669",
    "codeType": "preroll"
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 1440,
      "height": 244
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayCode":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48VkFTVCB2ZXJzaW9uPSIyLjAiPjwv
VkFTVD4=",
    "id": "adfox_156536764866112926",
    "cpm": 150,
    "currency": "RUB",
    "codeType": "preroll",
    "placementId": "296669"
  }]
}

Ссылка на VAST XML

Запрос

Ответ

curl 'https://bidder.ru/core/rtb/hb/bid'
-H 'Pragma: no-cache'
-H 'Origin: http://banners.adfox.ru'
-H 'Accept-Encoding: gzip, deflate, br'
-H 'Accept-Language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/67.0.3396.62 Safari/537.36'
-H 'Content-Type: text/plain'
-H 'Accept: */*'
-H 'Cache-Control: no-cache'
-H 'Referer: http://banners.adfox.ru/adfox/adfox
-header-bidding.html'
-H 'Connection: keep-alive' --data-binary 
'
{
  "places": [
  {
    "id": "div-1",
    "placementId": "8707",
    "codeType": "preroll"
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 1920,
      "height": 566
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayUrl":
"https://bidder.ru/core/code?pid=8707&bid=55968&idntfy=&fids=55968&rid=9727581640539884
549",
    "id": "div-1",
    "cpm": 15,
    "currency": "RUB",
    "codeType": "preroll",
    "placementId": "8707"
  }]
}

Combo

Формат Combo позволяет одновременно передавать баннеры и InPage-видео.

В запросе монетизатору приходит codeType: combo.

В зависимости от содержимого креатива codeType может принимать следующие значения:

codeType: html

Запрос

Ответ

curl 'https://bidder.com/bidder/adfox/bids'
-H 'pragma: no-cache'
-H 'cache-control: no-cache'
-H 'origin: https://www.site.ru'
-H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'content-type: text/plain'
-H 'accept: */*'
-H 'sec-fetch-site: cross-site'
-H 'sec-fetch-mode: cors'
-H 'referer: https://www.site.ru/'
-H 'accept-encoding: gzip, deflate, br'
-H 'accept-language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'

--data-binary 
'
{
  "places": [
  {
    "id": "adfox_1481556385598437",
    "placementId": "75d5e9c8ccb72a90cad8",
    "codeType": "combo"
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 1920,
      "height": 445
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayCode": "<iframe src='https://bidder.com/crative/65124681trg'>",
    "id": "adfox_1481556385598437",
    "cpm": 13.567,
    "currency": "RUB",
    "codeType": "html",
    "placementId": "75d5e9c8ccb72a90cad8",
    "size":
    {
      "width": 970,
      "height": 250
    }
  }]
}

codeType: js

Запрос

Ответ

curl 'https://bidder.com/ssp/adfox'
-H 'Connection: keep-alive'
-H 'Pragma: no-cache'
-H 'Cache-Control: no-cache'
-H 'Origin: https://site.ru'
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'Content-Type: text/plain'
-H 'Accept: */*'
-H 'Sec-Fetch-Site: cross-site'
-H 'Sec-Fetch-Mode: cors'
-H 'Referer: https://site.ru/post/29686-ochevidno-chto-kuzya-uzhe-ne-tot-igrok-kotorym-bylneskol-ko-let-nazad-vashingtonskiye-bolel-shchiki-o-rossiyskom-forvarde-keps?r=translations'
-H 'Accept-Encoding: gzip, deflate, br'
-H 'Accept-Language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'

--data-binary 
'
{
  "places": [
  {
    "id": "hb-1-1-pvq-dbtm-gfcg_1",
    "placementId": "80976",
    "codeType": "combo"
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 1440,
      "height": 329
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayUrl": "https://bidder.com/creative.js"
    "id": "hb-1-1-pvq-dbtm-gfcg_1",
    "cpm": 13,
    "currency": "RUB",
    "codeType": "js",
    "placementId": "80976",
    "size":
    {
      "width": 300,
      "height": 250
    }
  }]
}

codeType: inpage

Запрос

Ответ

curl 'https://exchange.bidder.com/ssp/adfox'
-H 'Connection: keep-alive'
-H 'Pragma: no-cache'
-H 'Cache-Control: no-cache'
-H 'Origin: https://banners.adfox.ru'
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/63.0.3239.132 Safari/537.36'
-H 'Content-Type: text/plain'
-H 'Accept: */*'
-H 'Sec-Fetch-Site: cross-site'
-H 'Sec-Fetch-Mode: cors'
-H 'Referer: https://banners.adfox.ru/191126/adfox/776727/bidderinpage.html'
-H 'Accept-Encoding: gzip, deflate, br'
-H 'Accept-Language: ru,ru;q=0.9,en-US;q=0.8,en;q=0.7'

--data-binary 
'
{
  "places": [
  {
    "id": "adfox_15747754996035865",
    "placementId": "296669",
    "codeType": "combo"
  }],
  "settings":
  {
    "currency": "RUB",
    "windowSize":
    {
      "width": 980,
      "height": 1743
    }
  }
}
'
--compressed

{
  "bids": [
  {
    "displayCode":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48VkFTVCB2ZXJzaW9uPSIyLjAiPjwv
VkFTVD4=",
    "id": "adfox_15747754996035865",
    "cpm": 150,
    "currency": "RUB",
    "codeType": "inpage",
    "placementId": "296669"
  }]
}

Обратиться в службу поддержки

Написать в чат

Написать письмо

Инструкция для подключения монетизаторов к Yandex Header Bidding

Описание процесса

Подключение собственной биддинг-платформы

Требования к монетизатору

Общий формат запроса

Параметры запроса

Request object

places

settings object

settings.windowSize object

Общий формат ответа

Параметры ответа

Response object

bid object

size object

codeType

Формат ответа, когда не удалось подобрать рекламу

Формат ответа, когда монетизатор возвращает информацию об ошибке

Запрос и ответ по нескольким баннерным местам

Запрос и ответ в зависимости от формата рекламы

Banner

codeType: banner

Fullscreen

Ссылка на код JavaScript

InPage

InStream

Base64 (URL safe) encoded VAST XML

Ссылка на VAST XML

Combo

codeType: html

codeType: js

codeType: inpage

Обратиться в службу поддержки

Была ли статья полезна?