Skip to content

Интеграция SSP ​

Эндпоинт ​

GET  /ssp/:feedId
POST /ssp/:feedId
  • :feedId — числовой идентификатор вашего фида. Хост, id фида и ключ фида выдаются при подключении.
  • Если вам выдан ключ фида, передавайте его в параметре key (query-параметр).

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

Обязательные ​

ПараметрОписаниеПример
ipIP-адрес пользователя8.8.8.8
uaUser-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 или pageURL страницы, где будет показана рекламаhttps://example.com/page
domainДомен сайта, если вы не передаёте URL страницыexample.com
userid или uidВаш идентификатор пользователяuser-123
pidИдентификатор паблишера42
subid1Sub-ID 1 для трекингаcampaign-a
subid2Sub-ID 2 для трекингаplacement-b
xffИсходный IP клиента (если запрос идёт через прокси/CDN)192.168.1.1,37.179.76.240
bidfloorМинимальная цена, которую вы принимаете, USD за 1000 показов0.5
ch-uaClient Hints: список брендов браузера"Chrome";v="107"
ch-ua-full-versionClient Hints: полная версия браузера107.0.5304.110
ch-ua-platformClient Hints: платформа ОСmacOS
ch-ua-platform-versionClient Hints: версия ОС13.0.1
ch-ua-modelClient Hints: модель устройстваPixel 7
ch-ua-mobileClient 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.com

POST — тело 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)
404id фида — не число

Формат ответа ​

Формат ответа настраивается для каждого фида при подключении. Два распространённых варианта:

Формат A: простой JSON ​

json
{
  "ads": [
    {
      "url": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101",
      "bid": 3.5
    }
  ]
}

Формат B: OpenRTB 2.5 ​

json
{
  "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/admURL трекинга клика — сюда нужно перенаправить пользователя при клике
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

json
{
  "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

json
{
  "error": "missing required fields: ua"
}

Примечания ​

  • Все цены — в USD.
  • Поле url / adm из ответа нужно использовать как URL перехода, когда пользователь взаимодействует с рекламой. Без этого клики не учитываются и не оплачиваются.
  • Если страна не передана, она определяется по IP. Явная передача повышает точность и сокращает задержку.
  • Браузер, тип устройства и ОС определяются по User-Agent автоматически.