Подключение инвентаря (SSP) к бирже

SSP подключается к Ibiza Exchange как источник трафика: вы отправляете запросы OpenRTB 2.6 на адрес вида https://<хост биржи>/bid/<имя источника>, биржа проводит аукцион среди подключенных демандов и возвращает одну ставку по цене нетто — за вычетом своей комиссии. Ниже — формат запроса, обязательные поля, коды ответа, состав ставки и какие уведомления нужно вызывать.

#Как это работает

ваш аукцион ──BidRequest──▶ Ibiza Exchange ──▶ деманды (DSP)
     ▲                            │
     └──── ставка нетто ◀─────────┘

1. Вы присылаете запрос на ставку.
2. Биржа поднимает ваш флор на свою комиссию, добавляет свой узел в цепочку поставки и рассылает запрос демандам — тем, кому разрешен этот тип трафика.
3. Лучшая ставка возвращается вам по цене нетто: нетто = гросс × (1 − комиссия). Если нетто ниже вашего флора, биржа отвечает no-bid.
4. Исход решает ваш аукцион: биржа участвует в нем как обычный покупатель.

Роль биржи между SSP и DSP описана в статье про ad exchange, а устройство SSP — в статье про SSP.

#1. Адрес и авторизация

Источник заводит команда биржи. Вы получаете:

Новый источник создается выключенным и включается после проверки цепочки на тестовых запросах.

POST /bid/mynetwork HTTP/1.1
Host: <хост биржи>
Content-Type: application/json
Authorization: Bearer <токен>

#2. Запрос

Тело — JSON BidRequest OpenRTB 2.6, до 256 КБ.

#Обязательные и важные поля

Что такое флор и как его выбирать — в статье bidfloor.

#Пример запроса

{
  "id": "a7f3c2d1-5e6b-4c8a-9f0e-1d2c3b4a5f60",
  "tmax": 300,
  "imp": [{
    "id": "1",
    "tagid": "slot-feed-2",
    "secure": 1,
    "bidfloor": 40.0,
    "bidfloorcur": "RUB",
    "native": { "request": "{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"wmin\":600,\"hmin\":300}},{\"id\":3,\"img\":{\"type\":1,\"w\":80,\"h\":80}}]}", "ver": "1.2" }
  }],
  "app": {
    "id": "1042",
    "bundle": "com.example.news",
    "publisher": { "id": "77" }
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 14; SM-A546E) ...",
    "ip": "176.59.10.20",
    "geo": { "country": "RUS" },
    "os": "Android", "osv": "14",
    "connectiontype": 6, "devicetype": 4,
    "ifa": "6f1c2a3b-4d5e-4f60-8a9b-0c1d2e3f4a5b"
  },
  "bcat": ["IAB25", "IAB26"]
}

#3. Время ответа

Если в запросе есть tmax, биржа укладывается в него: на свой аукцион она берет tmax минус 20 мс на сериализацию ответа, но не меньше 100 мс. Демандам уходит уже уменьшенный tmax — время, которое у них реально есть. Общий потолок обработки запроса на бирже — 500 мс. Почему время ответа так важно, разобрано в статье tmax.

#4. Ответ

Заголовки ответа со ставкой: Content-Type: application/json, X-OpenRTB-Version: 2.6, Cache-Control: no-store.

#Состав ставки

#Пример ответа

Деманд поставил 52 ₽, комиссия источника для примера — 15 %:

{
  "id": "a7f3c2d1-5e6b-4c8a-9f0e-1d2c3b4a5f60",
  "bidid": "e0b5c7a9-3f21-4d8e-b6a4-9c2d1e0f7a83",
  "cur": "RUB",
  "seatbid": [{
    "seat": "ibiza",
    "bid": [{
      "id": "b-77123-1",
      "impid": "1",
      "price": 44.2,
      "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[...],\"link\":{\"url\":\"https://...\"},\"imptrackers\":[\"https://...\"]}}",
      "nurl": "https://dsp.example/win?a=123&p=52",
      "burl": "https://dsp.example/bill?a=123&p=52",
      "lurl": "https://dsp.example/loss?a=123&reason=${AUCTION_LOSS}",
      "crid": "77123",
      "adomain": ["advertiser.example"],
      "mtype": 4,
      "ext": { "nroa": { "erid": "2SDnjbx1Xyz" } }
    }]
  }]
}

Макрос ${AUCTION_PRICE} в уведомлениях деманда биржа уже раскрыла своей ценой. Остальные макросы аукциона — ${AUCTION_ID}, ${AUCTION_LOSS}, ${AUCTION_MIN_TO_WIN} и другие — остаются вам: раскройте их по спецификации OpenRTB.

#5. Уведомления и учет показа

1. nurl — вызывайте при выигрыше ставки в вашем аукционе.
2. burl — вызывайте при оплачиваемом показе. По нему деманд бронирует расход.
3. lurl — вызывайте при проигрыше, раскрыв макросы причины и цены.
4. Разметку adm отображайте как есть. Биржа может встроить в креатив собственный пиксель показа — по нему ведется ее учет. Если вырезать незнакомые <img> и трекеры, показы не будут засчитаны.

Учет для источника настраивается одним из способов: по выигрышу или только по показу, подтвержденному пикселем. Режим согласуется при подключении. Подробнее про уведомления — в статье win notice.

#6. Прозрачность цепочки: sellers.json и schain

Биржа публикует https://<хост биржи>/sellers.json по стандарту IAB. Ваш источник в нем — запись типа INTERMEDIARY, а в цепочку schain каждого перепроданного запроса биржа дописывает узел с hp: 1 и sid, равным вашему seller_id в этом файле. Узел добавляется в ту же форму, в которой цепочка пришла (source.schain по 2.6 или source.ext.schain по 2.5); если цепочки не было, биржа создает ее в source.schain. Так деманды проверяют, через кого прошел трафик.

#7. Частые ошибки

#8. Чек-лист подключения

1. Получите от нас имя источника, адрес и, при необходимости, токен.
2. Отправьте тестовые запросы: один imp, явный bidfloorcur, заполненные device.ifa, device.ip, device.geo.country.
3. Убедитесь, что получаете 204 на no-bid и 200 со ставкой, а bid.impid совпадает с вашим imp.id.
4. Проверьте, что вызываете nurl, burl, lurl и не вырезаете пиксели из adm.
5. После проверки цепочки мы включаем источник на боевой трафик.

Если вы также покупаете трафик, то есть работаете как DSP, условия для демандов описаны в статье подключение деманда. Чтобы биржа не перепродавала ваш трафик вашему же деманду, такой деманд исключается в настройках источника — сообщите о нем при подключении.