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

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

> Как получать от нас рекламу push и popunder по JSON-фиду: адрес, параметры запроса, поля ответа, учёт показов и кликов, оплата и примеры.

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

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

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

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

- [Push](./feed-examples/push.md) — `format=push` или без параметра. Есть вариант с [учётом показа по картинке](./feed-examples/push.md#ответ-с-учетом-показа-по-картинке).
- [Popunder](./feed-examples/popunder.md) — `format=pop`.

Формат должен быть разрешён для подключения, иначе 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](https://docs.youtarget.com/rtb/glossary/bid-floor.md)) — параметр `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](https://docs.youtarget.com/rtb/glossary/cookie-sync.md). Синоним — `user_buyer_id`, при обоих берём `user_buyer_uid` |
| `sub_days` | рекомендуется для push | Сколько дней назад пользователь подписался на push, целое число |
| `sub_date` | нет | Дата подписки, Unix-время в секундах. При обоих берём `sub_days` |
| **Площадка** | | |
| `placement_tag_id` | да | ID [зоны](https://docs.youtarget.com/rtb/glossary/zone.md): по нему статистика и фильтры по зонам |
| `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, поэтому серверный запрос не сработает.
- Клики проверяем на качество трафика: открывайте ссылку в браузере того пользователя, которому показали объявление.

## Примеры

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

- [Push](./feed-examples/push.md)
- [Popunder](./feed-examples/popunder.md)
