Skip to content

Спецификация 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, ответ не сжимаем.

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

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:

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 макросы можно не подставлять.
  • Время события — момент, когда уведомление пришло к нам, а не время запроса. Учитывайте это при сверке на границе суток.
  • В варианте 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), в аукционе участвуют все, в ответе — разметка победителя; чтобы приходил один формат, попросите менеджера оставить у интеграции только его.

ПолеОбязательноОписание
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.

АссетNativePush
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да, для appID приложения в магазине.
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.5OpenRTB 2.6
API креативаapi, одно числоapis, массив
Язык креативаlanguagelangb
Тип разметкинет: различайте по 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 (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, см. пример.
  • Ставку ниже 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) не поддерживаются.

© Youtarget