Connection regulations

This document is a translation of «Connection regulations» in English. In case of conflict between the Russian version of «Connection regulations» and this translation - only the Russian version of «Connection regulations» is legally binding. The Russian version of «Connection regulations» can be found here: https://yandex.ru/legal/partner_connect/?lang=ru.

The real time bidding (RTB) host offers the following features:

  • Ad auctions and placement;

  • Binding information to user browsers.

Ad auctions and placement

The JavaScript code, which is embedded on the site to display ads from the RTB host, sends http/https GET requests to the RTB host containing both the site ID and the minimum price at which the ad can be displayed (MinCPM).

The RTB host then generates and sends a POST http request to the DSP in JSON format. The request is sent to the URL given in the DSP.

The RTB host waits 300 milliseconds for a response. If the DSP does not respond within this time, it will be understood that the DSP did not respond at all. Any response from the DSP must be in JSON format.

The RTB host will begin the auction after 300 milliseconds or as soon as it has received responses from all the DSPs. An auction can only be won by one DSP or not at all. Only responses that are equal to or exceed the MinCPM will be included in the auction. DSP responses are sorted in descending price order. The winner is then selected and the price reduced to:

  • the MinCPM

  • the price offered by the second place DCP + the bid increment.

The bid, actual price, win, loss or non-response information from all the DSPs, as well as the time (day) of the auction is logged by the RTB host.

In response to the JavaScript string received in the DSP response, the RTB host returns the adm field of the first "bid" array element of the first bidset (bidset[0].bid[0].adm) array element.

In case of absence of winning empty response is returned.

Example of RTB request to DSP

Example of DSP request to RTB

Units – cost band.

Only integers can be used in the price field.

The following table describes how the tokens given in the price field are converted to real prices depending on the cost type:

Units value

Ratio

Example

0

(default)

1 ruble CPM = 100 tokens

200 rubles for 1000 impressions should be depicted as 20 000 tokens.

A bid of 0.2 rub. per impression will be used in the auction.

1

1 ruble CPM = 1 token

200 rubles for 1000 impressions should be depicted as 200 tokens.

A bid of 0.2 rub. per impression will be used in the auction.

2

1 ruble CPM = 1000 tokens

200 rubles for 1000 impressions should be depicted as 200 000 tokens.

A bid of 0.2 rub. per impression will be used in the auction.

Binding information to browsers

The RTB host supports the http/https method, which can be used to "bind" a string to a user browser and retrieve this string when sending a request to the DSP.

The RTB host will begin transferring this data in any subsequent requests sent once the data has been bound to the browser.

This information is saved in the user's browser cookies performing the request to the RTB host.

The RTB will transfer data to the user over http.

The RTB host will then transfer this data to the DSP once a response has been received from the user.

The RTB host cannot guarantee the integrity of the data received from the user.

Specifications

We have the following user information:

  • IP-address — recorded in the format ip1.ip2.ip3.ip4, converted to: short_ip = ip1.ip2.ip3 (we only support IPv4);

  • Referer — the http-header value received by the RTB host;

  • UserAgent — the corresponding http-header value;

  • The DSP may bind the following data to a user:data — 27 characters;

  • The DSP may redirect the user to another URL after this call — location;

  • Previously set up key signature — key;

  • The DSP should generate the following signature: sign=crc32(short_ip.Referer.UserAgent.location.data.key), without any spaces;

  • Tag — the keyword that the RTB host uses to identify the DSP.

The following URL format must be used to link this data:

As a result, the user should receive one of the following responses:

  • If "location" is not present: 200 OK

  • If "location" is present: 302 Redirect

  • If the signature is invalid: 404 Not found