Спецификация OpenRTB
Как продавать трафик в Youtarget по OpenRTBОткрытый стандарт IAB для обмена запросами и ставками между SSP и DSP в реальном времени. 2.5 и 2.6; пары «запрос — ответ» — на странице Примеры OpenRTB.
Спецификации
- OpenRTB 2.5 и OpenRTB 2.6: версию выбирают для интеграции при подключении.
- Native 1.2: в запросе Native Request 1.1 или 1.2, в ответе Native Response 1.1.
- VAST 4.2: отдаём VAST Wrapper 2.0–4.2 и VAST InLine 3.0.
- Валюта одна на интеграцию, её согласуют при подключении.
- Модели оплаты — CPMЦена за тысячу показов. (за 1000 показов) и CPC (за клик), модель задаётся для интеграции.
- Запрос можно сжать gzip, ответ не сжимаем.
Поддерживаемые форматы
- Баннер — пример, в том числе MRAID в приложениях и DOOH (только 2.6).
- Interstitial — пример.
- Видео — пример, в том числе rewarded и полноэкранное.
- Native — пример.
- Push — пример.
- Popunder — пример.
- Мультиформат — пример.
- Аудио — не поддерживается.
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. |
| OpenRTB 2.6 | Ответ в форме 2.6, принимаем контекст dooh. |
| HTML-баннеры как есть | Как OpenRTB 2.6, но HTML-баннер приходит в adm в исходном виде, без нашей JS-обёртки. |
| Popunder по OpenRTB | Любой imp считаем попандером, в adm — ссылка для открытия. Ответ в форме 2.5. |
Вариант, форматы, модель оплаты, валюту, событие учёта показа, время на ответ и лимит запросов в секунду настраивает менеджер. В запросе вариант не передаётся.
Уведомления
В каждой ставке есть nurl и burl, иногда lurl:
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макросы можно не подставлять. - Время события — момент, когда уведомление пришло к нам, а не время запроса. Учитывайте это при сверке на границе суток.
- В варианте 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Сопоставление идентификаторов пользователя между двумя рекламными системами.. |
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 места размещения, по нему заводим зонуКонкретное место показа рекламы на площадке, например блок на странице сайта.. Рекламодатели таргетируют зоны и видят по ним статистику, поэтому держите tagid постоянным. |
bidfloor | нет | float, минимальная цена, см. Цена и 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. |
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 пользователя у нас после синхронизации. |
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. |
nurl, burl | да | Уведомления о выигрыше и об оплачиваемом показе. |
lurl | нет | Уведомление о проигрыше, есть не в каждой ставке — поддерживайте его. |
adid, crid | да | ID креативаРекламное объявление внутри кампании — баннер, нативный блок, Push, Pop или видео.. |
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. Внутри
<Impression>,<Tracking>дляstart, квартилей,completeиskip,<Error>с[ERRORCODE], в InLine — ещё<ClickThrough>. - Native и push — Native Response 1.1 JSON-строкой без обёртки
native: ассеты,link.url,link.clicktrackers,imptrackersиeventtrackers(event1— показ,2— видимость 50 % по MRC,3— видимость 100 % по MRC,4— видимость видео 50 %;method1— пиксель). - 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, см. пример.- Ставку ниже
imp.bidfloorне отправляем. Другого floorМинимальная ставка, ниже которой показ не продаётся. не учитываем. 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) не поддерживаются.