Connecting monetizers to Yandex Header Bidding

Header Bidding is a programmatic technology that you can use to survey multiple monetizers when a user loads a site page and select the offer with the highest bid.

The Header Bidding library isn't part of the Adfox ad tags and must be downloaded separately. It isn't open source. Adding new monetizers, interacting with those already connected, and all work on the library is carried out by Yandex.

Process description

The header-bidding.js library sends a POST request with an array of places objects from the page. The array describes the parameters of all banner placements that bids and creatives are requested for.
The monetizer sends a response with a 200 code that contains a bids array with bids and creatives for the banner placements where they want to display ads. In this case:
- A single response contains the bids from all participating monetizers.
- Creatives are sent only to placements where bids are indicated.
- If the monetizer hasn't selected an ad for any placement, an empty array is sent.
- All required fields of each bids object from the bids array are filled in. If at least one of the required fields isn't filled in, the bid is declared invalid and excluded from the auction.
- Win-notice and lose-notice aren't supported.
- The Access-Control-Allow-Origin headings with the incoming origin must be set, and so must Access-Control-Allow-Credentials: true.
Creatives are passed in the displayUrl or displayCode parameter depending on the type of content. In this case:
- HTML creatives are transmitted either by an HTML string in displayCode or by a link to an HTML file in displayUrl.
- JavaScript creatives are transmitted either by a JavaScript string in displayCode or by a link to a JavaScript file in displayUrl. The JavaScript code must be executed asynchronously.
- Video ads must match IAB VAST 2.0 specifications.
- For VAST, modified Base64 for URL encoding is used, where + and / of the standard Base64 are replaced by - and _, respectively.
- Yandex Header Bidding supports a maximum of three redirects inside Wrapper.

Connecting custom bidding placement

Monetizer requirements

CORS support.
HTTPS support.

General request format

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

Request parameters

Request object

Parameter	Description	Required
`places`	Object containing information about the requested placements.	Yes
`settings`	Object containing additional information.	Yes

places

Parameter	Description	Required
`id`	Adfox container ID.	Yes
`placementId`	Placement ID on the monetizer's side.	Yes
`sizes`	2D array with expected banner dimensions. For example, `[[300, 250]]` or `[[300, 250], [640, 480]]`. Dimensions are only transmitted for `codeType: banner` and `combo`.	No
`targetRef`	Address of the site page that the banner request was sent from.	Yes
`codeType`	Requested ad format. To learn more, see the codeType section.	No
`{additional_field}`	The site owner and the monetizer can agree to use custom fields for the Header Bidding settings on the page, if required. These custom fields are passed in the request at the root level of the `places` field.	No

settings object

Parameter	Description	Required
`currency`	Currency in which the bid must be returned in the response. Allowed values are RUB, USD, EUR, CHF, KZT, BYN, and UAH.	Yes
`windowSize`	Object containing information about the window size.	Yes

settings.windowSize object

Parameter	Description	Required
`width`	Window width obtained by the `window.innerWidth` method.	Yes
`height`	Window height obtained by the `window.innerHeight` method.	Yes

General response format

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

Response parameters

Response object

Parameter	Description	Required
`bids`	Array containing information about bids and creatives.	Yes

bid object

Parameter	Description	Required
`id`	Adfox container ID from the request.	Yes
`displayUrl`	Link to an HTML creative, JS code, or VAST XML. The response may contain the `displayCode` or `displayUrl` parameter.	Yes
`displayCode`	String with an HTML creative, JS code, or VAST XML with base64 encoding (for VAST only). The response may contain the `displayCode` or `displayUrl` parameter.	Yes
`cpm`	Bid amount as a positive fraction. This parameter supports up to three decimal places, truncating any excess digits.	Yes
`codeType`	Provided ad format. To learn more, see the codeType section.	Yes
`placementId`	Placement ID on the monetizer's side.	Yes
`currency`	Bid currency from the response. Allowed values are RUB, USD, EUR, CHF, KZT, BYN, and UAH.	Yes
`size`	Object containing information about the size of the creative. Dimensions are only transmitted for `codetype: banner` and `combo`.	Yes
`disableFullscreen`	Setting `disableFullscreen: true` prevents Adfox from rendering a fullscreen banner substrate. If the monetizer renders their own substrate, it will appear in the banner. For details on setting up fullscreen banners, see Features of ad tags.	No

size object

Parameter	Description	Required
`width`	Width of the creative in pixels.	Yes
`height`	Height of the creative in pixels.	Yes

codeType

Optional. If the codeType field isn't included in the request, the Banner request format is assumed by default.

Allowed values:

Request	Response
Missing: `codeType`	Allowed: `codeType: html` or `js` (Banner format).
`codeType: inpage`	`codeType: inpage` (Video format).
`preroll`, `midroll`, or `postroll`	`codeType` must match the value provided in the request (InStream format).
`codeType: combo`	Allowed: `codeType: html` or `js` (Banner format). `inpage` (Video format).

Response format when selecting an ad was not possible

{
  "bids": []
}

Response format when monetizer returns error information

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

Request or response for multiple banner placements

In this example, Yandex sends information on three banner placements in the places array, and the monetizer refuses to bid on one of them.

Request

Response

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,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
    }
  }]
}

Request and response depending on the ad format

With the Banner format, you can show ads as banners that may take up part of the screen.

Request

Response

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,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

The Fullscreen format contains ads that occupy the entire screen of a device.

Link to JavaScript code

For the Fullscreen format, the response must include "codeType": "js". The <script> tag with the src attribute value from the displayUrl parameter is exported to the container. The dimensions provided in the response must be as follows:

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

Request

Response

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,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

With the InPage format, you can show video ads in the site content.

VAST XML will be played in the Yandex video player.

There are two options:

Pass base64 encoded VAST XML in the displayCode parameter.
Pass a reference to VAST XML in the displayUrl parameter.

Request

Response

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,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

With the InStream format, you can show video ads (pre-roll, pause-roll, post-roll, mid-roll) in a player with custom video content.

There are two options:

Pass base64 (URL safe) encoded VAST XML in the displayCode parameter.
Pass a reference to VAST XML in the displayUrl parameter.

In the request body, the monetizer receives adBreakType in the codeType field:

preroll
midroll
postroll

Base64 (URL safe) encoded VAST XML

Request

Response

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,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"
  }]
}

Link to VAST XML

Request

Response

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,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

With the Combo format, you can send banners and InPage videos at the same time.

In the request, the monetizer receives codeType: combo.

Depending on the content of the creative, codeType can have the following values:

codeType: html

Request

Response

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,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

Request

Response

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,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

Request

Response

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,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"
  }]
}

Contact support

Send an email

Connecting monetizers to Yandex Header Bidding

Process description

Connecting custom bidding placement

Monetizer requirements

General request format

Request parameters

Request object

places

settings object

settings.windowSize object

General response format

Response parameters

Response object

bid object

size object

codeType

Response format when selecting an ad was not possible

Response format when monetizer returns error information

Request or response for multiple banner placements

Request and response depending on the ad format

Banner

codeType: banner

Fullscreen

Link to JavaScript code

InPage

InStream

Base64 (URL safe) encoded VAST XML

Link to VAST XML

Combo

codeType: html

codeType: js

codeType: inpage

Contact support

Was the article helpful?