Skip to content

Спецификация JSON-фида ​

JSON-фид отдаёт рекламу Youtarget без OpenRTB: GET-запрос с параметрами в URL, в ответ — JSON-массив готовых объявлений.

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

  • Запрос — HTTPS GET, все данные в query-параметрах. Тела нет, сжатие не нужно.
  • Ответ — JSON-массив до cnt объявлений по убыванию цены или HTTP 204 без тела.
  • Форматы — push и popunder, один формат на запрос.
  • Валюта — валюта вашего аккаунта, модель оплаты — CPMЦена за тысячу показов. или CPC. Обе задаются при подключении и в запросе и ответе не передаются.
  • Поле cpc — цена объявления: при CPC за клик, при CPM за 1000 показов (несмотря на имя).

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

Формат должен быть разрешён для подключения, иначе 204. На native, banner, video и audio всегда 204, на любое другое значение format — 400.

TIP

Без format=pop придёт push, даже если место показа — popunder.

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

Подключение заводит менеджер и присылает адрес интеграции с вашим ID подключения в параметре id. Остальные параметры добавляете вы. Адреса на странице условные.

text
https://feed.example.com/bid?id=9b2f4c1e7a3d4e5f8a6b0c1d2e3f4a5b
  • POST тоже принимается, но тело не читается: данные всё равно передавайте в URL.
  • Заголовки не нужны: IP и User-Agent пользователя передаются параметрами ip и ua.
  • URL-кодируйте значения: в ua и lang есть пробелы, запятые и точки с запятой.
  • Тестового режима нет.

Что настраивает менеджер:

  • Валюта и модель оплаты — в чём выражены floor и cpc.
  • Разрешённые форматы — какие значения format дадут рекламу.
  • Минимальная цена (bid floorМинимальная ставка, ниже которой показ не продаётся.) — параметр floor в запросе её перекрывает.
  • Время на ответ и лимит запросов в секунду — передать их в запросе нельзя; если аукцион не успел или лимит превышен, ответ 204.
  • Способ учёта показа и событие оплаты — какие ссылки из ответа вызывать, см. Учёт показа и оплата. Узнайте их до запуска: если вызывать не ту ссылку, показы не засчитаются.

Параметров согласия (GDPR, CCPA), COPPA и schain в фиде нет. Если для вашего трафика они обязательны, обсудите это с менеджером до подключения.

Коды ответа ​

КодЧто значитЧто делать
200Есть реклама, в теле JSON-массивПоказать объявление, вызвать ссылки учёта показа
204Рекламы нет, тела нетПоказать свою рекламу или ничего
400Нет id, неизвестное значение format или req_id не UUIDИсправить запрос
403Подключение неактивноОбратиться к менеджеру
404Неизвестный idСверить адрес с тем, что прислал менеджер
500Внутренняя ошибкаПовторить позже

Причины 204: нет объявлений выше floor, формат не разрешён или не поддерживается, аукцион не уложился во время, превышен лимит запросов, запрос отсечён фильтрами подключения или проверкой качества трафика.

  • Ответ 200 с пустым массивом [] обрабатывайте как 204.
  • Причину отказа ответ не содержит: поля nbr нет.
  • Разбирайте тело как JSON по коду 200, не по заголовку Content-Type.

Параметры запроса ​

«Да» — без параметра запрос получит 400 или его почти никто не купит: без ip нет гео, без ua — устройства, без ID зоны и домена не работают фильтры рекламодателей. Технически сервер отклоняет только запрос без id. «Рекомендуется» — без параметра ставок будет меньше. Неизвестные параметры игнорируются.

ПараметрОбязательноОписание
Подключение
idдаID подключения, 32 hex-символа, уже есть в адресе. Без него 400, неизвестный — 404
formatтолько для popunderpush (по умолчанию) или pop
Пользователь и устройство
ipдаIPv4 или IPv6 пользователя: страна, город, оператор, тип соединения
uaдаUser-Agent браузера пользователя: устройство, ОС, браузер
langрекомендуетсяКод языка или Accept-Language, например de-DE,de;q=0.9; сводим к базовому коду
sec-ch-ua-modelнетClient Hint модели устройства, кавычки допустимы
sec-ch-ua-platformнетClient Hint ОС
sec-ch-ua-platform-versionнетClient Hint версии ОС
user_idнетID пользователя на вашей стороне
user_buyer_uidнетНаш ID пользователя из cookie-syncСопоставление идентификаторов пользователя между двумя рекламными системами.. Синоним — user_buyer_id, при обоих берём user_buyer_uid
sub_daysрекомендуется для pushСколько дней назад пользователь подписался на push, целое число
sub_dateнетДата подписки, Unix-время в секундах. При обоих берём sub_days
Площадка
placement_tag_idдаID зоныКонкретное место показа рекламы на площадке, например блок на странице сайта.: по нему статистика и фильтры по зонам
context_idнетID сайта или приложения
context_typeнет2 — приложение, любое другое значение или отсутствие — сайт
domainда, для сайтовДомен без схемы
bundleда, для приложенийBundle ID приложения
catнетКатегории IAB контента площадки через запятую
ratingнетВозрастной рейтинг контента, учитываем при отборе креативов
subidнетВаш subid источника: статистика и фильтры по subid
Ограничения и служебные
bcatнетЗапрещённые категории IAB через запятую
badvнетЗапрещённые домены рекламодателей через запятую
floorнетМинимальная цена в единицах cpc, число с точкой. Перекрывает bid floor из настроек; некорректное значение игнорируется
cntнетСколько объявлений вернуть, от 1 до 10. По умолчанию 1, 0 и не число — тоже 1
req_idнетВаш ID запроса в формате UUID, иначе 400. Без него создаём свой

ID зоны — первое непустое и не равное 0 значение из placement_tag_id, context_id, subid в этом порядке.

Ответ ​

Все поля приходят всегда, пустое значение — "".

ПолеФорматОписание
idpush, popunderID объявления, UUID. Он же стоит во всех ссылках объявления
impidpush, popunderПорядковый номер в ответе: "1", "2"
cridpush, popunderID креатива
campaign_idpush, popunderID кампании, число
categorypush, popunderКатегория креатива IAB или ""
titlepushЗаголовок уведомления
textpushТекст уведомления
image_urlpush, popunderPush — большая картинка или ссылка учёта показа. Popunder — служебное поле, загружать не нужно
icon_urlpushИконка
click_urlpush, popunderPush — ссылка клика. Popunder — страница, которую открыть в окне popunder
nurlpush, popunderУведомление о выигрыше
burlpush, popunderУведомление об оплачиваемом событии
cpcpush, popunderЦена в валюте аккаунта: за клик при CPC, за 1000 показов при CPM
  • Макросы креатива {city} и {date} уже раскрыты: показывайте title и text как есть.
  • floor задаётся в тех же единицах, что cpc. Пример: подключение в USD с CPM, floor=0.5 — не дешевле 0,5 USD за 1000 показов.

Учёт показа и оплата ​

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

ВариантКогда показ засчитанЧто делаете вы
По nurlПри вызове nurlВызвать nurl, когда объявление показано
По burlПри вызове burlВызвать burl, когда объявление показано
По картинке или видимый показ по картинке (push)При загрузке image_urlЗагрузить image_url с устройства пользователя в момент показа. Ссылка засчитывает показ и перенаправляет (302) на картинку
PopunderПри открытии click_urlОткрыть click_url в окне popunder в браузере пользователя

Правила вызова ссылок:

  • Вызывайте ссылки ровно как пришли: макросов в них нет, цена в уведомлениях не передаётся.
  • nurl и burl — методом GET (POST тоже принимается), с сервера или из браузера.
  • Повторный вызов отвечает 200, но второй раз не засчитывается: ретраи безопасны.
  • Неверная, изменённая или устаревшая ссылка отвечает 400. Ссылки действуют ограниченное время: вызывайте их в момент показа и клика.
  • Загружайте image_url и icon_url по ссылкам из ответа, не подменяйте и не кешируйте: у части объявлений их загрузка и есть показ.

За что платим (цена события — cpc из ответа):

Модель оплатыСобытие оплатыЗа что платим
CPCне заданоКлик: открытие click_url
CPMпо nurl / по burlВызов nurl / burl
CPMпо показуPush — загрузка ссылки учёта показа из image_url или icon_url. Popunder — открытие click_url
CPM, popunderне заданоОткрытие click_url

Для push с CPM событие оплаты должно быть задано — если менеджер его не указал, попросите выбрать.

Клик ​

  • click_url открывается в браузере пользователя: для push — по клику на уведомление, для popunder — сразу при показе.
  • Мы перенаправляем на лендинг кодом 302 или HTML-страницей с редиректом на JavaScript или meta refresh, поэтому серверный запрос не сработает.
  • Клики проверяем на качество трафика: открывайте ссылку в браузере того пользователя, которому показали объявление.

Примеры ​

Запросы и ответы для каждого формата:

© Youtarget