Спецификация JSON-фида
JSON-фид отдаёт рекламу Youtarget без OpenRTB: GET-запрос с параметрами в URL, в ответ — JSON-массив готовых объявлений.
Спецификации
- Запрос — HTTPS GET, все данные в query-параметрах. Тела нет, сжатие не нужно.
- Ответ — JSON-массив до
cntобъявлений по убыванию цены или HTTP 204 без тела. - Форматы — push и popunder, один формат на запрос.
- Валюта — валюта вашего аккаунта, модель оплаты — CPMЦена за тысячу показов. или CPC. Обе задаются при подключении и в запросе и ответе не передаются.
- Поле
cpc— цена объявления: при CPC за клик, при CPM за 1000 показов (несмотря на имя).
Поддерживаемые форматы
- Push —
format=pushили без параметра. Есть вариант с учётом показа по картинке. - Popunder —
format=pop.
Формат должен быть разрешён для подключения, иначе 204. На native, banner, video и audio всегда 204, на любое другое значение format — 400.
TIP
Без format=pop придёт push, даже если место показа — popunder.
Подключение
Подключение заводит менеджер и присылает адрес интеграции с вашим ID подключения в параметре id. Остальные параметры добавляете вы. Адреса на странице условные.
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 | только для popunder | push (по умолчанию) или 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 в этом порядке.
Ответ
Все поля приходят всегда, пустое значение — "".
| Поле | Формат | Описание |
|---|---|---|
id | push, popunder | ID объявления, UUID. Он же стоит во всех ссылках объявления |
impid | push, popunder | Порядковый номер в ответе: "1", "2" |
crid | push, popunder | ID креатива |
campaign_id | push, popunder | ID кампании, число |
category | push, popunder | Категория креатива IAB или "" |
title | push | Заголовок уведомления |
text | push | Текст уведомления |
image_url | push, popunder | Push — большая картинка или ссылка учёта показа. Popunder — служебное поле, загружать не нужно |
icon_url | push | Иконка |
click_url | push, popunder | Push — ссылка клика. Popunder — страница, которую открыть в окне popunder |
nurl | push, popunder | Уведомление о выигрыше |
burl | push, popunder | Уведомление об оплачиваемом событии |
cpc | push, 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, поэтому серверный запрос не сработает.
- Клики проверяем на качество трафика: открывайте ссылку в браузере того пользователя, которому показали объявление.
Примеры
Запросы и ответы для каждого формата: