<!-- https://docs.youtarget.com/rtb/ssp/openrtb.html -->

# Спецификация OpenRTB

> Как продавать трафик в Youtarget по OpenRTB 2.5 и 2.6: форматы, адрес, уведомления, коды ответа, макросы, поля запроса и ответа, цена и floor.

Как продавать трафик в Youtarget по [OpenRTB](https://docs.youtarget.com/rtb/glossary/openrtb.md) 2.5 и 2.6; пары «запрос — ответ» — на странице [Примеры OpenRTB](./examples/banner.md).

## Спецификации

- [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) и [OpenRTB 2.6](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md): версию выбирают для интеграции при подключении.
- [Native 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf): в запросе Native Request 1.1 или 1.2, в ответе Native Response 1.1.
- [VAST 4.2](https://iabtechlab.com/wp-content/uploads/2019/06/VAST_4.2_final_june26.pdf): отдаём VAST Wrapper 2.0–4.2 и VAST InLine 3.0.
- Валюта одна на интеграцию, её согласуют при подключении.
- Модели оплаты — [CPM](https://docs.youtarget.com/rtb/glossary/cpm.md) (за 1000 показов) и CPC (за клик), модель задаётся для интеграции.
- Запрос можно сжать gzip, ответ не сжимаем.

## Поддерживаемые форматы

- Баннер — [пример](./examples/banner.md), в том числе MRAID в приложениях и DOOH (только 2.6).
- Interstitial — [пример](./examples/interstitial.md).
- Видео — [пример](./examples/video.md), в том числе rewarded и полноэкранное.
- Native — [пример](./examples/native.md).
- Push — [пример](./examples/push.md).
- Popunder — [пример](./examples/popunder.md).
- Мультиформат — [пример](./examples/multiformat.md).
- Аудио — не поддерживается.

Push, popunder, **HTML-баннеры как есть** и **native в баннерном слоте** включает менеджер для интеграции: по полям запроса их не отличить.

## Главное

> [!IMPORTANT]
> - **Обрабатываем только `imp[0]`.** Остальные `imp` игнорируем: одно место показа — один запрос.
> - **Креатив всегда в `adm`.** `nurl` — только уведомление, разметку по нему не отдаём.
> - **`${AUCTION_PRICE}` — открытым числом.** Подставляйте в `nurl` и `burl` цену вида `0.85`: если макрос остался как есть или цена зашифрована, уведомление отклоняется и показ не засчитывается.
> - **Нет ставки — `204` без тела.**
> - **Тестового режима нет.** Запрос с `test=1` обрабатываем как обычный: ставки и уведомления боевые.

## Подключение

- Адрес один на все варианты интеграции, например `https://bid.example.com/bid?id=5b0f3c1e-8a2d-4f6b-9c7e-2d4a6b8c0e1f`. Параметр `id` — UUID интеграции, полный адрес присылает менеджер.
- Метод `POST`, тело — JSON BidRequest. Соединение можно держать открытым (keep-alive).
- `Content-Type: application/json` — обязательно; `Content-Encoding: gzip` — если сжимаете, другие кодировки не поддерживаются.
- `X-OpenRTB-Version` не читаем: в обеих версиях понимаем написания полей 2.5 и 2.6, а если пришли оба, берём поле 2.6.
- Ответ со ставкой приходит с `Content-Type: application/json; charset=utf-8` и `X-OpenRTB-Version: 2.5` или `2.6`. В варианте **Popunder по OpenRTB** разбирайте тело как JSON, не опираясь на заголовки.

| Вариант интеграции | Чем отличается |
| --- | --- |
| OpenRTB 2.5 | Ответ в форме 2.5, см. [отличия 2.5 и 2.6](#отличия-2-5-и-2-6). |
| OpenRTB 2.6 | Ответ в форме 2.6, принимаем контекст `dooh`. |
| **HTML-баннеры как есть** | Как OpenRTB 2.6, но HTML-баннер приходит в `adm` в исходном виде, без нашей JS-обёртки. |
| **Popunder по OpenRTB** | Любой `imp` считаем попандером, в `adm` — ссылка для открытия. Ответ в форме 2.5. |

Вариант, форматы, модель оплаты, валюту, событие учёта показа, время на ответ и лимит запросов в секунду настраивает менеджер. В запросе вариант не передаётся.

## Уведомления

В каждой ставке есть `nurl` и `burl`, иногда `lurl`:

```text
https://notify.example.com/wn?id=<bid.id>&t=<токен>&price=${AUCTION_PRICE}
https://notify.example.com/bn?id=<bid.id>&t=<токен>&price=${AUCTION_PRICE}
https://notify.example.com/ln?id=<bid.id>&t=<токен>&price=${AUCTION_PRICE}&loss=${AUCTION_LOSS}&mtw=${AUCTION_MIN_TO_WIN}
```

- SSP вызывает `nurl`, когда ставка выиграла, `burl` — когда показ состоялся и его можно оплачивать, `lurl` — когда ставка проиграла. Метод `GET` или `POST`.
- Вызывайте сразу после события: уведомления принимаем ограниченное время после ставки.
- Не меняйте и не обрезайте параметры `id` и `t`, не кодируйте ссылку повторно.
- Показ засчитывает событие, согласованное при подключении: `nurl`, `burl`, наш пиксель показа в `adm` или клик при CPC. Вызывайте и `nurl`, и `burl`, даже если учёт идёт по одному из них.
- Цену выше нашей ставки не учитываем: засчитываем по ставке. Повторное уведомление по той же ставке второй раз не засчитывается.
- В `lurl` макросы можно не подставлять.
- Время события — момент, когда уведомление пришло к нам, а не время запроса. Учитывайте это при [сверке](../common/reconciliation.md) на границе суток.
- В варианте **Popunder по OpenRTB** в `nurl` и `burl` нет макроса цены, засчитываем по нашей ставке. Показ засчитываем, когда пользователь открыл ссылку из `adm`, или по `nurl` или `burl`, если так договорились. Ссылку, открытую ботом, не засчитываем.

| Ответ | Что значит |
| --- | --- |
| `200` | Принято. Повторное уведомление тоже получает `200`. |
| `400` | Нет `id` или он не UUID, нет токена `t` или он неверный, срок приёма истёк, цена не число. |

## Коды ответа

| Код | Что значит | Что делать |
| --- | --- | --- |
| `200` | Есть ставка, тело — BidResponse. | Показать `adm`, вызвать уведомления. |
| `204` | Ставки нет, тело пустое. Так же отвечаем при превышении лимита запросов, если запрос не прошёл проверку качества трафика или фильтры интеграции, или истёк `tmax`. Причину (`nbr`) не передаём. | Ничего, это обычный no-bid. |
| `400` | Нет `id` в адресе; тело не JSON или не распаковывается; нет `id` запроса; `imp` пустой; у `imp` нет `id`; в `imp` нет ни `banner`, ни `video`, ни `native`, ни `audio` (в варианте **Popunder по OpenRTB** объекты формата не нужны). | Исправить запрос. |
| `403` | Интеграция не активна. | Связаться с менеджером. |
| `404` | Интеграции с таким `id` нет. | Проверить адрес. |

Запрос не отклоняем, если `device.ip` пустой (но без IP нет гео, и кампании с геотаргетингом не купят показ), у `video` нет `mimes`, `linearity` или `protocols`, `native.request` не читается или пришли сразу `site` и `app`.

## Макросы

| Макрос | Где | Чем заменить |
| --- | --- | --- |
| `${AUCTION_PRICE}` | `nurl`, `burl`, `lurl` | Цена клиринга открытым числом с точкой, в валюте `cur` и единицах модели оплаты. В `nurl` и `burl` — обязательно. |
| `${AUCTION_LOSS}` | `lurl` | Код причины проигрыша по OpenRTB. |
| `${AUCTION_MIN_TO_WIN}` | `lurl` | Минимальная цена, которая выиграла бы аукцион. |
| `[ERRORCODE]` | `<Error>` в VAST | Код ошибки VAST, подставляет видеоплеер. |

Других макросов в наших ссылках нет, шифрование цены не поддерживается. В `adm` макросы цены SSP не используются.

## Bid request

«Да» — без поля запрос получит `400` или его почти никто не купит: без `device.ip` нет гео, без `device.ua` — устройства, без `tagid` и домена не работают фильтры рекламодателей. «Рекомендуется» — без поля ставок будет меньше. Поля, которых нет в таблицах, можно передавать: на ставку они не влияют. Где написание в 2.5 и 2.6 различается, понимаем оба, а если пришли оба, берём поле 2.6.

### BidRequest

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `id` | да | `string`, возвращаем в `BidResponse.id`. |
| `imp` | да | `object[]`, читаем только первый элемент. |
| `site`, `app`, `dooh` | да | Контекст показа, один из объектов. `dooh` — только 2.6. |
| `device` | да | По нему определяем гео, тип устройства, ОС и браузер. |
| `user` | рекомендуется | Пользователь и его ID после [cookie-sync](https://docs.youtarget.com/rtb/glossary/cookie-sync.md). |
| `regs` | рекомендуется | Флаг GDPR, см. [Приватность](#приватность). |
| `tmax` | рекомендуется | `integer`, время на ответ в миллисекундах, см. [Ограничения](#ограничения). |
| `cur` | нет | `string[]`. Если передан, в нём должна быть валюта интеграции, иначе `204`. |
| `bcat` | нет | Категории IAB, креативы которых не покупаем. |
| `badv` | нет | Домены рекламодателей, креативы которых не покупаем. |
| `wlangb` (2.6), `wlang` | нет | Язык для подбора креативов, порядок — под таблицей. |
| `test` | нет | Не включает тестовый режим, см. [Главное](#главное). |

Язык берём первый найденный: `wlangb` или `wlang`, затем `content.langb` или `content.language`, затем `device.langb` или `device.language`. Код BCP 47 сводим к языку: `de-AT` → `de`.

Принимаем, но не используем: `bapp`, `acat`, `cattax`, `allimps`.

### imp

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `id` | да | `string`, возвращаем в `bid.impid`. |
| `banner`, `video`, `native` | да | Хотя бы один объект. Несколько в одном `imp` — мультиформат. |
| `tagid` | да | ID места размещения, по нему заводим [зону](https://docs.youtarget.com/rtb/glossary/zone.md). Рекламодатели таргетируют зоны и видят по ним статистику, поэтому держите `tagid` постоянным. |
| `bidfloor` | нет | `float`, минимальная цена, см. [Цена и floor](#цена-и-floor). |
| `bidfloorcur` | нет | Валюта `bidfloor`, код ISO 4217. |
| `instl` | нет | `1` — полноэкранное размещение. Принимаем число и строку. |
| `rwdd` (2.6), `ext.rewarded` (2.5) | только для видео | `1` — rewarded-видео. Принимаем и `video.ext.rewarded`. |

Если `tagid` пустой или `"0"`, ID зоны берём из `site.id`, `app.id` или `dooh.id`, а если нет и их — из `publisher.ext.subid`.

Принимаем, но не используем: `secure` (разметка всегда по https), `pmp` (сделок нет, `dealid` в ответе не бывает), `exp`, `audio` (на запрос только с `audio` отвечаем `204`).

> [!TIP]
> Interstitial — это `instl=1` вместе с `banner` или `video`. Отдаём только креативы для полноэкранного размещения, разметка как у обычного баннера или видео.

> [!TIP]
> Мультиформат: покупаем форматы, которые есть в `imp` и включены у интеграции. Если подходят несколько (например, native и push на `imp.native`), в аукционе участвуют все, в ответе — разметка победителя; чтобы приходил один формат, попросите менеджера оставить у интеграции только его.

### banner

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `format` | рекомендуется | `object[]`, допустимые размеры. Размеры с нулём отбрасываем. |
| `w`, `h` | рекомендуется | Размер, если нет `format`. |
| `api` | нет | `5` (MRAID 2) или `6` (MRAID 3) в приложении — можем отдать MRAID-креатив. `3` (MRAID 1) не учитываем. |

Принимаем, но не используем: `btype`, `battr`, `mimes`, `wmin`, `wmax`, `hmin`, `hmax`.

### video

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `protocols` | рекомендуется | `integer[]`, по ним выбираем вид и версию VAST, см. [Выбор VAST](#выбор-vast). |
| `minduration`, `maxduration` | рекомендуется | Допустимая длительность ролика в секундах. |
| `plcmt` (2.6), `placement` (2.5) | рекомендуется | Тип размещения: instream, outstream и другие. Если пришли оба, берём `plcmt`. |
| `startdelay` | нет | Позиция в ролике: pre-, mid- или post-roll. |
| `skip`, `skipafter` | нет | Можно ли пропустить ролик и через сколько секунд. |
| `playbackmethod` | нет | Как запускается воспроизведение. |
| `companionad`, `companiontype` | нет | Сопутствующий баннер (end-card). |
| `api` | нет | Поддерживаемые API. В мультиформатном `imp` объединяем `api` всех объектов. |

Принимаем, но не используем: `mimes`.

### native

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `request` | да | `string`: Native Request 1.1 или 1.2 JSON-строкой, без обёртки `{"native": …}`. |
| `ver` | нет | Версия Native Request. |

Внутри `request` читаем `assets`, `plcmtcnt`, `plcmttype`, `context`, `seq` и `eventtrackers`. Принимаем, но не используем: `battr`.

| Ассет | Native | Push |
| --- | --- | --- |
| `title` | Заголовок | Заголовок |
| `img`, `type=3` (основное изображение) | Картинка креатива | Крупная картинка |
| `img`, `type=1` (иконка) | — | Иконка |
| `data`, `type=2` (описание) | — | Текст уведомления |
| `data`, `type=12` (текст кнопки) | Текст кнопки | — |

Если обязательный ассет (`required: 1`) нечем заполнить, например `video` или `data` с `type=1`, креатив не ставим. Необязательные ассеты, которых у креатива нет, не возвращаем.

> [!TIP]
> Push и popunder приходят на обычный `imp.native` (popunder — ещё и на `imp.banner`). Формат задаёт настройка интеграции у менеджера, а не поле запроса.

### site, app и dooh

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `id` | рекомендуется | ID площадки, запасной ID зоны. |
| `domain` | да, для `site` | Домен площадки. |
| `bundle` | да, для `app` | ID приложения в магазине. |
| `cat` | нет | Категории площадки IAB. |
| `publisher.ext.subid` | нет | Sub-ID вашего источника: рекламодатели видят его и могут таргетировать. |
| `content.cat` | нет | Категории контента. |
| `content.langb` (2.6), `content.language` | нет | Язык контента. |
| `content.contentrating` | нет | Возрастной рейтинг по шкале MPAA, по нему отбираем креативы. |

`dooh` — только в 2.6, передавайте его вместо `site` и `app`.

### device

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `ip` | да | Гео определяем только по IP. |
| `ipv6` | нет | Используем, если нет `ip`. |
| `ua` | да | Тип устройства, ОС и браузер. |
| `make`, `model`, `os`, `osv` | нет | Производитель, модель, ОС и её версия. |
| `langb` (2.6), `language` | нет | Язык устройства. |
| `ifa` | нет | Рекламный ID. ID из одних нулей отбрасываем, при `gdpr=1` не используем. |

Принимаем, но не используем: `geo` — гео берём по IP.

### user

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `id` | рекомендуется | ID пользователя на вашей стороне. |
| `buyeruid` | рекомендуется | ID пользователя у нас после [синхронизации](../common/cookie-sync.md). |
| `consent` (2.6), `ext.consent` (2.5) | нет | Строка согласия TCF, не разбираем. |

### regs

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `gdpr` (2.6), `ext.gdpr` (2.5) | рекомендуется | `1` — на пользователя распространяется GDPR. Принимаем `1`, `"1"` и `true`. |
| `coppa`, `us_privacy`, `gpp`, `gpp_sid` | нет | Запрос не ломают, см. [Приватность](#приватность). |

## Bid response

Ответ со ставкой — `200` и BidResponse.

### BidResponse и seatbid

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `id` | да | `id` вашего запроса. |
| `cur` | да | Валюта интеграции, не зависит от `cur` запроса. |
| `seatbid` | да | `object[]`, ставки. |
| `seatbid.seat` | да | ID покупателя (seat). |

Не заполняем: `bidid`, `nbr`.

### bid

| Поле | Обязательно | Описание |
| --- | --- | --- |
| `id` | да | ID ставки, UUID. Он же — параметр `id` в наших уведомлениях. |
| `impid` | да | `imp[0].id` вашего запроса. |
| `price` | да | `float`, ставка в валюте `cur` и единицах модели оплаты. |
| `adm` | да | Разметка креатива, см. [Что приходит в adm](#что-приходит-в-adm). |
| `nurl`, `burl` | да | Уведомления о выигрыше и об оплачиваемом показе. |
| `lurl` | нет | Уведомление о проигрыше, есть не в каждой ставке — поддерживайте его. |
| `adid`, `crid` | да | ID [креатива](https://docs.youtarget.com/rtb/glossary/creative.md). |
| `cid` | да | ID кампании. |
| `adomain` | нет | `string[]`, домен рекламодателя. |
| `cat` | нет | `string[]`, категории креатива IAB. |
| `w`, `h` | нет | Размер креатива, правило — под таблицей. |
| `protocol` | только для видео | Какой VAST отдали. |
| `apis` (2.6), `api` (2.5) | нет | API креатива, например `6` у MRAID 3. |
| `langb` (2.6), `language` (2.5) | нет | Язык креатива. |
| `mtype` (2.6) | нет | Тип разметки: `1` — баннер и native в баннерном слоте, `2` — видео, `4` — native и push. У попандера нет. |
| `dur` (2.6) | только для видео | Длительность ролика в секундах. |
| `ext.cpc` | только для CPC | Цена клика, совпадает с `price`. |

`w` и `h` у баннера — размер HTML-креатива, если он фиксированный, иначе совпавший запрошенный размер, иначе ближайший по пропорциям, иначе первый из запрошенных. У native и push — размер основного изображения.

Не заполняем: `attr`, `iurl`, `bundle`, `dealid`, `exp`, `qagmediarating`, `cattax`, `slotinpod`.

### Отличия 2.5 и 2.6

| Что | OpenRTB 2.5 | OpenRTB 2.6 |
| --- | --- | --- |
| API креатива | `api`, одно число | `apis`, массив |
| Язык креатива | `language` | `langb` |
| Тип разметки | нет: различайте по `adm` (HTML, VAST, JSON) | `mtype` |
| Длительность видео | нет | `dur` |

### Что приходит в adm

Показывайте `adm` без изменений: трекеры показа, видимости и клика уже внутри. Разметка и трекеры всегда по https.

- Баннер, interstitial, DOOH — HTML-фрагмент: `<div>` и асинхронная загрузка нашего JS, который рисует креатив в iframe и сам отправляет трекеры. JS должен выполняться, ID контейнера новый в каждом ответе.
- MRAID — HTML креатива с подключением `mraid.js` (его предоставляет SDK приложения) и нашими трекерами. В `bid.apis` (`bid.api` в 2.5) — `6`, если заявлен MRAID 3, иначе `5`.
- **HTML-баннеры как есть** — исходный HTML креатива и пиксели показа `<img>`, для сторонних тегов, которые не работают в iframe. Клики и видимость не отслеживаем; баннеры-картинки и HTML-файлы приходят в обычной подаче.
- **Native в баннерном слоте** — HTML, как у баннера, под размер слота: `mtype=1`, `w` и `h` равны размеру слота.
- Видео — VAST XML, вид и версия — по таблице [Выбор VAST](#выбор-vast). Внутри `<Impression>`, `<Tracking>` для `start`, квартилей, `complete` и `skip`, `<Error>` с `[ERRORCODE]`, в InLine — ещё `<ClickThrough>`.
- Native и push — Native Response 1.1 JSON-строкой без обёртки `native`: ассеты, `link.url`, `link.clicktrackers`, `imptrackers` и `eventtrackers` (`event` `1` — показ, `2` — видимость 50 % по MRC, `3` — видимость 100 % по MRC, `4` — видимость видео 50 %; `method` `1` — пиксель).
- Popunder — Native Response 1.1, в `link.url` ссылка для открытия в новом окне или вкладке; картинка — если запрошен `img` с `type=3` и она есть у креатива.
- **Popunder по OpenRTB** — ссылка строкой, откройте её как popunder или новую вкладку. Ссылка ведёт на лендинг редиректом или через промежуточную страницу.
- Мультиформат — разметка формата, который выиграл: в 2.6 его видно по `mtype`, в 2.5 — по содержимому `adm`.

### Выбор VAST

| Что в `video.protocols` | Что отдаём |
| --- | --- |
| Есть Wrapper: `5` (2.0), `6` (3.0), `8` (4.0), `12` (4.1), `14` (4.2) | VAST Wrapper самой новой из заявленных Wrapper-версий |
| Только InLine: `2` (2.0), `3` (3.0), `7` (4.0), `11` (4.1), `13` (4.2) | VAST InLine 3.0 |
| Пусто или нет поля | VAST Wrapper 4.2 |

DAAST (`9`, `10`) не поддерживаем. Outstream и instream различаем по `plcmt` (`placement` в 2.5), разметка у них одинаковая.

## Цена и floor

- `price`, `bidfloor` и `${AUCTION_PRICE}` — в валюте интеграции и единицах модели оплаты: CPM — за 1000 показов, CPC — за клик. При CPC цена дублируется в `bid.ext.cpc`, см. [пример](./examples/more.md#native-с-оплатои-за-клик).
- Ставку ниже `imp.bidfloor` не отправляем. Другого [floor](https://docs.youtarget.com/rtb/glossary/bid-floor.md) не учитываем.
- `bidfloorcur` пересчитываем в валюту интеграции, регистр кода не важен. Если `bidfloorcur` нет или код незнаком, считаем floor в валюте интеграции.
- `cur` ответа — всегда валюта интеграции.
- В варианте **Popunder по OpenRTB** при CPM цена указана за 1000 попандеров, при CPC — за один; поля `ext` нет.

## Приватность

- GDPR: `regs.gdpr` (2.6) или `regs.ext.gdpr` (2.5). При `gdpr=1` не используем `device.ifa`.
- Строку согласия TCF из `user.consent` (2.6) или `user.ext.consent` (2.5) не разбираем: решение об `ifa` принимаем только по флагу `gdpr`.
- `regs.coppa`, `us_privacy`, `gpp` и `gpp_sid` запрос не ломают. Как мы их учитываем, уточните у менеджера.

## Ограничения

- `tmax` отсчитываем от момента, когда получили запрос, сетевую задержку закладывайте сами. Не успели — отвечаем `204`.
- Если для интеграции задано своё время на ответ, оно важнее `tmax`.
- У интеграции есть лимит запросов в секунду, запросы сверх него получают `204`.
- На баннер и видео отвечаем одной ставкой, на native — не больше `plcmtcnt`, по умолчанию одной.
- Сделки (PMP) не поддерживаются.
