Инструкция для подключения монетизаторов к 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.
- HTML-креатив передается HTML-строкой в
Подключение собственной биддинг-платформы
Требования к монетизатору
Общий формат запроса
{
"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.
Возможные значения:
Запрос |
Ответ |
Отсутствует |
Допустимы |
|
|
|
Должен быть тот же |
|
Допустимы:
|
Формат ответа, когда не удалось подобрать рекламу
{
"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
Формат Banner позволяет показывать рекламные объявления в виде баннеров, которые могут занимать часть экрана.
codeType: 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"
}]
}