Интеграция SSP
Эндпоинт
GET /ssp/:feedId
POST /ssp/:feedId:feedId— числовой идентификатор вашего фида. Хост, id фида и ключ фида выдаются при подключении.- Если вам выдан ключ фида, передавайте его в параметре
key(query-параметр).
Параметры запроса
Обязательные
| Параметр | Описание | Пример |
|---|---|---|
ip | IP-адрес пользователя | 8.8.8.8 |
ua | User-Agent пользователя | Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/107.0 |
Необязательные
| Параметр | Описание | Пример |
|---|---|---|
key | Ключ вашего фида, если он выдан | a1b2c3 |
lang | Язык пользователя (ISO 639-1) | en |
country | Код страны (ISO 3166-1 alpha-2). Если не передан, определяется по IP. | US |
ref или page | URL страницы, где будет показана реклама | https://example.com/page |
domain | Домен сайта, если вы не передаёте URL страницы | example.com |
userid или uid | Ваш идентификатор пользователя | user-123 |
pid | Идентификатор паблишера | 42 |
subid1 | Sub-ID 1 для трекинга | campaign-a |
subid2 | Sub-ID 2 для трекинга | placement-b |
xff | Исходный IP клиента (если запрос идёт через прокси/CDN) | 192.168.1.1,37.179.76.240 |
bidfloor | Минимальная цена, которую вы принимаете, USD за 1000 показов | 0.5 |
ch-ua | Client Hints: список брендов браузера | "Chrome";v="107" |
ch-ua-full-version | Client Hints: полная версия браузера | 107.0.5304.110 |
ch-ua-platform | Client Hints: платформа ОС | macOS |
ch-ua-platform-version | Client Hints: версия ОС | 13.0.1 |
ch-ua-model | Client Hints: модель устройства | Pixel 7 |
ch-ua-mobile | Client Hints: признак мобильного | ?0 |
Client Hints принимаются и под именами заголовков (sec-ch-ua, sec-ch-ua-platform, sec-ch-ua-mobile, …), а также ch-ua-arch, ch-ua-bitness и ch-ua-full-version-list.
Подисточники (плейсменты). Передавайте id подисточника в каждом запросе: вы увидите статистику по каждому подисточнику, а слабый подисточник можно будет приостановить отдельно, не трогая весь фид. Имя параметра согласуется при подключении и настраивается на вашем фиде.
Таймаут. Сообщите при подключении, сколько вы ждёте нашего ответа (ваш tmax): мы зададим его на фиде и будем отвечать в этот срок. Если OpenRTB-запрос несёт tmax, используется он.
Способы запроса
GET — query-параметры
Передавайте все поля в query-параметрах URL:
GET /ssp/27?key=YOUR_FEED_KEY&ip=8.8.8.8&ua=Mozilla/5.0%20Chrome/107.0&lang=en&ref=https://example.comPOST — тело JSON
Отправьте JSON. Формат тела настраивается для каждого фида при подключении.
POST /ssp/27
Content-Type: application/json
{
"device": {
"ip": "5.6.7.8",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/107.0",
"geo": {
"country": "DE"
},
"language": "de"
}
}POST — тело XML
То же, что JSON, но в XML. Формат тела настраивается для каждого фида при подключении.
POST /ssp/27
Content-Type: application/xml
<BidRequest>
<Device>
<IP>5.6.7.8</IP>
<UA>Mozilla/5.0 Chrome/107.0</UA>
</Device>
<Geo>
<Country>DE</Country>
</Geo>
<Language>de</Language>
</BidRequest>Query-параметры и тело можно сочетать: значения из тела важнее, query-параметры заполняют то, чего нет в теле.
Ответ
Коды ответа HTTP
| Код | Значение |
|---|---|
| 200 | Реклама найдена — в теле ответа ставка |
| 204 | Рекламы нет — так же отвечаем на неизвестный или неактивный фид |
| 400 | Нет обязательных полей или запрос не разобран |
| 403 | Неверный ключ фида (key) |
| 404 | id фида — не число |
Формат ответа
Формат ответа настраивается для каждого фида при подключении. Два распространённых варианта:
Формат A: простой JSON
{
"ads": [
{
"url": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101",
"bid": 3.5
}
]
}Формат B: OpenRTB 2.5
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"seatbid": [
{
"bid": [
{
"id": "85aedd2b-84e7-4dfe-9355-87db56e81101",
"impid": "1",
"price": 3.5,
"adm": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101"
}
]
}
]
}Поля ответа
| Поле | Описание |
|---|---|
url/adm | URL трекинга клика — сюда нужно перенаправить пользователя при клике |
bid/price | Ставка в USD (CPM) |
id | Уникальный идентификатор ставки |
Примеры
Успешный запрос (GET)
Запрос:
GET /ssp/27?ip=8.8.8.8&ua=Mozilla/5.0%20(Windows%20NT%2010.0)%20Chrome/107.0&lang=en&country=US&ref=https://publisher.com/pageОтвет: 200 OK
{
"ads": [
{
"url": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101",
"bid": 3.5
}
]
}Рекламы нет
Запрос:
GET /ssp/27?ip=8.8.8.8&ua=Chrome/107&lang=enОтвет: 204 No Content
(пустое тело)
Нет обязательных полей
Запрос:
GET /ssp/27?ip=8.8.8.8Ответ: 400 Bad Request
{
"error": "missing required fields: ua"
}Примечания
- Все цены — в USD.
- Поле
url/admиз ответа нужно использовать как URL перехода, когда пользователь взаимодействует с рекламой. Без этого клики не учитываются и не оплачиваются. - Если страна не передана, она определяется по IP. Явная передача повышает точность и сокращает задержку.
- Браузер, тип устройства и ОС определяются по User-Agent автоматически.