Общая информация
Интеграция
Узнать подробнее об интеграции по протоколам Feed и OpenRTB:
Bid Request/Response
Описание поддерживаемых параметров и примеры Bid Request/Response:
Процесс интеграции
1. Ознакомление с документацией.
2. DSP создает и выдает эндпоинт/фид под соответствующий формат рекламы и тип интеграции.
3. Проводятся тесты на предмет работоспособности интеграции и наличия расхождений между данными системы Kadam и DSP.
4. Если расхождения в пределах нормы и отсутствуют технические проблемы, запускается интеграция в полноценном рабочем режиме.
Ключевые моменты
Kadam поддерживает протоколы Feed, OpenRTB 2.5, Native 1.1, Native 1.2;
Чтобы подключить новую DSP, необходимо убедиться, что вы поддерживаете передачу необходимых параметров и готовы отправлять запросы и получать от нас ответы;
В документе указаны параметры, поддерживаемые Kadam, если какие-то параметры не описаны, значит их поддержка не реализована.
Cookie Matching
Cookie Matching позволяет сопоставить ваш файл cookie, например идентификатор пользователя, который просматривал ваш веб-сайт, с соответствующим идентификатором пользователя Kadam. Чтобы это сопоставление произошло, SSP или DSP необходимо проявить инициативу и показать DMP пиксель партнеру. Цель показа пикселя партнера заключается в том, чтобы передать ему идентификатор пользователя по своей версии и сохранить связь в таблице матчинга. Хранителями могут выступать: SSP, DSP, оба.
Для настройки Cookie Matching необходимо обратиться к менеджеру Kadam.
Feed интеграция
Feed интеграция
Эта документация объясняет, как DSP могут интегрировать свои платформы с Kadam, используя стандарт Feed.
Bid Request/Response
Поддерживаемые типы рекламы:
Native;
Push;
On site push (inpage);
iOS calendar push;
Pops.
Feed Bid Request
Feed Bid Request
Описание поддерживаемых параметров
Следующие объекты следует отправлять в GET параметрах запроса:
Параметр | Описание | Использование | Обязательный |
sid | endpoint ID | Уникализация потока в Kadam. Выдается Kadam | Обязательный |
skey | Ключ API | Выдается Kadam |
|
ua | user agent | Для определения ос, устройства, браузера пользователя на стороне Kadam | Обязательный |
ip | IP-адрес пользователя | Для определения геолокации устройства пользователя на стороне Kadam | Обязательный либо IP, либо IPv6 |
uid | ID пользователя в системе SSP | Для уникализации пользователя | Обязательный |
limit | Ограничение количества креативов в ответе | Если лимит отсутствует в запросе и на блоке, считается как 1 по умолчанию |
|
language | Основной язык браузера, кодировка ISO 3166-1 alpha-2 | Для определения языка браузера. Пример передачи: &language=ru-RU или &language=ru. Если параметр language не заполнен, заполнен некорректно или не передается, он считается "неопределенным", это снижает выкуп |
|
subage / subage_dt / subage0 / subage_ts | Возраст подписки пользователя | Если параметр subage не заполнен, заполнен некорректно или не передается, он считается "неопределенным", это снижает выкуп. Для первого дня подписки ожидается: subage=1, subage0=0, subage_dt - фактическая дата подписки, subage_ts - фактическая дата подписки (unixtime) | Обязательный |
pid | ID паблишера | В параметре ожидается ID паблишера (сайта, вебмастера) на стороне SSP | Обязательный |
cat | IAB-категория домена | По умолчанию на меинстриме - IAB24, на адалте - IAB25-3 | Необязательный |
page | Домен страницы | Ожидается страница | Желательный |
format | Формат трафика | Cu, pops - для кликандера; Native, teaser - для тизера; По умолчанию - push | Необязательный |
Примеры Bid Request
PUSH
/feed ?sid=5 &skey=5azqxvgap5yNsm5X5rg5PMsgDD &ua=Mozilla%2F5.0+%28Linux%3B+Android+9%3B+SAMSUNG+SM-A105FN%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+SamsungBrowser%2F12.1+Chrome%2F79.0.3945.136+Mobile+Safari%2F537.36 &ip=127.1.0.0 &uid=Xef5LfyUte-tzwpV5-fMV &limit=1 &language=en &pid=1 &subage=2 &cat=126 &page=example.com |
POPS
/feed ?sid=555 &format=cu &ua=Mozilla%2F5.0+%28Linux%3B+Android+10%3B+SM-J600F%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F91.0.4472.88+Mobile+Safari%2F537.36 &ip=127.1.0.0 &uid=555555555 &limit=5 &language=fa-IR &pid=5555555 &page=example.com |
ON SITE PUSH (INPAGE)
/feed ?sid=5 &skey=5azqxvgap5yNsm5X5rg5PMsgDD &ua=Mozilla%2F5.0+%28Linux%3B+Android+9%3B+SAMSUNG+SM-A105FN%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+SamsungBrowser%2F12.1+Chrome%2F79.0.3945.136+Mobile+Safari%2F537.36 &ip=127.1.0.0 &uid=Xef5LfyUte-tzwpV5-fMV &limit=1 &language=en &pid=1 &cat=126 &page=example.com |
IOS CALENDAR PUSH
/feed ?sid=555 &skey=ca555555f555ec5a5a5ff55cc5b5fb5c &ua=iOS%2F14.4+%5558D52%29+dataaccessd%2F1.0 &ip=127.1.0.0 &uid=0.00695555.5515680055292 &language=en &subage_dt=2021-07-10 &pid=5555555555 &limit=1 |
NATIVE
/feed ?sid=555 &skey=b5cb555d5efcd555ade5555a5eaa5f55 &ua=Mozilla%2F5.0+%28Linux%3B+Android+11%3B+SM-T500%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F91.0.4472.120+Safari%2F537.36 &ip=127.1.0.0 &uid=5b5aa555-bd55-555b-a5d5-55f55f5c55df &language=de &pid=55 &page=example.com &format=native |
Feed Bid Response
Feed Bid Response
Описание поддерживаемых параметров (для изменения нейминга параметров в Bid Response обращайтесь к нашему менеджеру)
Параметр | Описание | Использование | Обязательный |
id | ID материала |
|
|
impid | ID импрешна |
|
|
crid (adid, cid) | ID креатива |
| да |
nurl | URL уведомление о выигрыше | Возможно высылать: Отдельным полем, В составе icon_url , В составе image_url. Переключение режима ответа происходит через менеджера. |
|
link (click_url) | Кликовая ссылка |
| да |
campaing_id (cid) | ID кампании |
|
|
category | ID категории (секции) материала |
|
|
title | Заголовок объявления |
| да |
description (desc) | Заголовок объявления |
|
|
text | Текст объявления |
|
|
image_url | Ссылка на изображение материала |
| да |
icon_url | Ссылка на иконку + nurl | Используется в push-уведомлениях |
|
cpc (price, bid) | Ставка (bid) материала |
| да |
image | Ссылка на картинку + nurl |
|
|
result | Объект ставок | Используется в Pops |
|
listing | Массив объектов ставок |
|
|
result.listing
Параметр | Описание | Использование | Обязательный |
url | Ссылка для перехода по объявлению |
|
|
bid | Ставка |
|
|
Примеры Bid Response:
PUSH
1. Icon_url содержит в себе nurl и icon_url
2. С отдельным полем “nurl”
POPS
ON SITE PUSH (INPAGE)
IOS CALENDAR PUSH
1
2
NATIVE
OpenRTB интеграция
OpenRTB интеграция
Эта документация объясняет, как DSP могут интегрировать свои платформы с Kadam, используя стандарт OpenRTB.
Bid Request/Response
Поддерживаемые типы рекламы:
Native;
Native (teaser);
Banner;
Video;
Push;
inpage (on site push);
iOS calendar push;
Pops (Clickunder).
Интеграция с баннерными DSP
Для корректного отображения кликов в нашей статистике просьба передавать в параметре “adm“ следующее:
1 вариант (предпочтительный)
Кликовый макрос: ${CLICK_URL};
Вашу кликовую ссылку в URL-endcode формате.
Например, ваша кликовая ссылка - “http://example.ru”. В таком случае вам необходимо передавать её как "${CLICK_URL}http%3A%2F%2Fexample.ru", где мы заменим макрос на нашу кликовую ссылку, пользователь попадёт сначала к нам, а потом мы средиректим его по endcode-ссылке, что шла после макроса, к вам.
2 вариант
Кликовый макрос:${CLICK_URL_ENC}.
В данном кейсе мы заменим макрос на нашу endcode-кликовую ссылку. Пользователь вначале попадает к вам, а потом вы редиректите на нас по той ссылке, что мы заменили вместо макроса. Пример - "http://example.com/example..${CLICK_URL_ENC}".
OpenRTB Bid Request
OpenRTB Bid Request
Описание поддерживаемых параметров
Следующие объекты следует отправлять в кодировке JSON в request body:
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор аукциона |
| Обязательный |
at | Тип аукциона. Для SSP, работающих по CPC, всегда проходит аукцион первой цены | Для аукциона первой цены at=1. По умолчанию 2 - Second Price | Необязательный |
cur | Валюта аукциона. Допустимые значения: USD — американский доллар | По умолчанию используется валюта SSP | Необязательный |
imp | Массив объектов: требования к рекламным материалам для размещения | Используется для подбора релевантных требованиям материалов | Обязательный |
site | Данные о сайте в объекте site |
| Обязательный site или app |
app | Подробная информация о приложении |
| Обязательный site или app |
user | Данные о пользователе в объекте user |
| Обязательный |
badv | Список доменов, которые необходимо исключить из аукциона |
| Необязательный |
bcat | Заблокированные категории рекламодателей, использующие категории контента IAB |
|
|
device | Данные об устройстве пользователя в объекте device |
| Обязательный |
imp
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор показа |
| Обязательный |
secure | Тип соединения. Возможные варианты: 0 — указывает, что нужно подбирать материалы доступные и по http и https протоколам. 1 — указывает, что нужно подбирать материалы доступные только по https | Значение по умолчанию - “https” | Необязательный |
bidfloor | Минимальная стоимость показа | По умолчанию 0 | Необязательный |
bidfloorcur | Валюта стоимости показа | По умолчанию USD, валидные значения в ISO-4217 | Необязательный |
tagid | Идентификатор конкретного плейсмента объявления или рекламного тега, который был использован для инициирования аукциона |
| Рекомендуется |
ext | Дополнительные параметры |
|
|
native | Параметр для Native и Push форматов, где необходимо передавать ассеты (заголовки, описание, картинки, иконки и т.д) |
| Обязательный для Native, Push |
banner | Параметр для формата Banner |
| Обязательный для Banner Ad |
video | Параметр для формата Video |
| Обязательный для Video Ad |
instl | Валидные значения: 1 - полноэкранная реклама (interstitial), 0 - нет | По умолчанию 0 | Необязательный |
battr | Заблокированные параметры |
| Необязательный |
imp.ext
Параметр | Описание | Использование | Обязательный |
subage / subage_dt / subage0 / subage_ts | Возраст подписки пользователя | Если параметр subage не заполнен, заполнен некорректно или не передается, он считается "неопределенным", это снижает выкуп. Для первого дня подписки ожидается: subage=1, subage0=0, subage_dt - фактическая дата подписки, subage_ts - фактическая дата подписки (unixtime) | Обязательный для Push Ad |
imp.native
Параметр | Описание | Использование | Обязательный |
request | Запрос в кодировке JSON для Push и Native материалов | Варианты: openrtb.native.string - JSON текст запроса; openrtb.native - запрос является JSON объектом. Он аналогичен openrtb.native.string, только в случае строки запрос кодируется в JSON текст | Обязательный |
ver | Версия спецификации нативной рекламы, которой соответствует запрос |
|
|
imp.native.request
Параметр | Описание | Использование | Обязательный |
plcmtcnt | Количество одинаковых размещений в этом шаблоне |
|
|
imp.banner
Параметр | Описание | Использование | Обязательный |
w | Ширина баннера в пикселях |
| Обязательный либо “w” и “h”, либо “format” |
h | Высота баннера в пикселях |
| Обязательный либо “w” и “h”, либо “format” |
format | Массив объектов, представляющих допустимые размеры баннера |
| Обязательный либо “w” и “h”, либо “format” |
imp.video
Параметр | Описание | Использование | Обязательный |
mimes | Whitelist MIME-типов медиа-файла. Пример: ["video/mp4", "video/webm"] |
| Да |
minduration | Минимальная длительность ролика, секунды |
| Рекомендуется |
maxduration | Максимальная длительность ролика, секунды |
| Рекомендуется |
protocols | Массив поддерживаемых VAST-версий (см. enum ниже) |
| Да |
w | Ширина плеера в пикселях |
| Рекомендуется |
h | Высота плеера в пикселях |
| Рекомендуется |
startdelay | Задержка перед стартом, сек. 0 = pre-roll, -1 = mid-roll, -2 = post-roll |
| Нет |
linearity | 1 = Linear / in-stream, 2 = Non-linear / overlay |
| Нет |
api | Массив поддерживаемых API frameworks (см. enum ниже) |
| Нет |
minbitrate | Минимально допустимый битрейт MediaFile, kbps | Используется при подборе медиа-файла | Нет |
maxbitrate | Максимально допустимый битрейт MediaFile, kbps | Используется при подборе медиа-файла | Нет |
pos | Позиция плеера на странице: 0 = Unknown, 1 = Above the Fold, 3 = Below the Fold, 4 = Header, 5 = Footer, 6 = Sidebar, 7 = Full Screen |
| Нет |
playbackmethod | Массив способов автозапуска: 1 = auto play sound on, 2 = auto play sound off, 3 = click-to-play, 4 = mouse-over, 5 = enter viewport sound on, 6 = enter viewport sound off |
| Нет |
delivery | Массив поддерживаемых типов доставки: 1 = streaming, 2 = progressive, 3 = download |
| Нет |
companiontype | Массив типов компаньонов: 1 = Static Resource, 2 = HTML Resource, 3 = iFrame Resource | Если плеер умеет показывать companion ads | Нет |
Enum для protocols (парсер Kadam поддерживает VAST 4.x):
1 — VAST 1.0
2 — VAST 2.0
3 — VAST 3.0
4 — VAST 1.0 Wrapper
5 — VAST 2.0 Wrapper
6 — VAST 3.0 Wrapper
7 — VAST 4.0
8 — VAST 4.0 Wrapper
11 — VAST 4.1
12 — VAST 4.1 Wrapper
13 — VAST 4.2
14 — VAST 4.2 Wrapper
Enum для api:
1 — VPAID 1.0
2 — VPAID 2.0
3 — MRAID-1
4 — ORMMA
5 — MRAID-2
6 — MRAID-3
7 — OMID-1
site
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор сайта | Для уникализации сайта, создания black- или white-листов партнерами | Обязательный |
domain | Домен страницы | Для внутренней классификации доменов в системе Kadam | Обязательный |
page | Полный адрес страницы | Для внутренней классификации сайтов в системе Kadam | Рекомендуемый |
name | Название сайта |
|
|
publisher | Данные о владельце сайта |
|
|
content | Подробная информация о содержимом сайта |
|
|
cat | Список IAB категорий сайта. Массив строк | Можно не передавать, если заполнен параметр domain, так как Kadam ведется внутренняя классификация доменов | Рекомендуемый |
ext | Дополнительные параметры сайта |
|
|
site.publisher
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор сайта |
|
|
app
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор приложения | Для уникализации приложения, создания black- или white-листов партнерами | Обязательный |
domain | Домен приложения. Например, “Foo.com” | Для внутренней классификации доменов в системе Kadam | Обязательный |
page | Полный адрес страницы | Для внутренней классификации сайтов в системе Kadam |
|
name | Название приложения или псевдоним паблишера |
|
|
bundle | Уникальный ID приложения для конкретной платформы. Примеры: IOS - 1453331063 Android - com.foo.mygame |
|
|
storeurl | App store URL установленного приложения |
|
|
cat | IAB-категория страницы | Можно не передавать, если заполнен параметр domain, так как Kadam ведется внутренняя классификация доменов | Рекомендуемый |
ver | Версия спецификации нативной рекламы, которой соответствует запрос |
|
|
publisher | Данные о владельце приложения |
|
|
ext | Дополнительные параметры приложения |
|
|
app.publisher
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор владельца приложения |
|
|
name | Имя владельца приложения |
|
|
user
Параметр | Описание | Использование | Обязательный |
id | Уникальный идентификатор пользователя в системе | Если не заполнен, то Kadam генерирует самостоятельно |
|
buyeruid | Уникальный идентификатор пользователя в системе Kadam | Используется, если настроен Cookie Matching. Является приоритетней user.id |
|
yob | Год рождения в виде целого 4-значного числа |
|
|
gender | Пол | "M" = мужчина; "F" = женщина; "O" = неизвестно |
|
ext | Дополнительные параметры пользователя |
|
|
user.ext
Параметр | Описание | Использование | Обязательный |
consent | Строка согласия IAB Transparency and Consent Framework (TCF) v2, полученная от платформы управления согласием (CMP) паблишера. Структура строки определяется IAB TCF v2 | Это поле будет заполнено, если издатель интегрирован с CMP для TCF v2, и эта CMP указывает, что GDPR применяется к данному рекламному запросу и предоставляет действительную строку согласия |
|
device
Параметр | Описание | Использование | Обязательный |
ifa | Уникальный идентификатор устройства в формате UUID | Если имеется в реквесте, используется в качестве user.id | Необязательный |
geo | Геолокация устройства пользователя |
| Необязательный |
ip | Ближайший к пользователю IPv4 адрес | Для определения геолокации устройства пользователя на стороне Kadam | Обязательный либо IP, либо IPv6 |
ipv6 | Ближайший к пользователю IPv6 адрес | Для определения геолокации устройства пользователя на стороне Kadam | Обязательный либо IP, либо IPv6 |
ua | User agent | Для определения ос, устройства, браузера пользователя на стороне Kadam | Обязательный |
js | Поддержка JS. 1 - присутствует, 0 - отсутствует |
|
|
language | Основной язык браузера, кодировка ISO-639-1-alpha-2 | Для определения языка браузера. Пример передачи: &language=ru-RU или &language=ru. Если параметр language не заполнен, заполнен некорректно или не передается, он считается "неопределенным", это снижает выкуп |
|
device.geo
Параметр | Описание | Использование | Обязательный |
utcoffset | Количество часов, на которое смещен часовой пояс от UTC |
|
|
country | Код страны (по стандарту ISO-3166-1 Alpha-3) |
|
|
ext
Параметр | Описание | Использование | Обязательный |
bsection | Используется для указания категорий материалов, которые запрещены в рамках данного реквеста. Целочисленный вид | Для получения полного списка категорий необходимо обратиться к менеджеру | Необязательный |
btags | Используется для указания тегов материалов, которые запрещены в рамках данного реквеста. Целочисленный вид | Для получения полного списка тегов необходимо обратиться к менеджеру | Необязательный |
Примеры Bid Request
POPS
{ "id": "5ccab55d-a5a5-5555-5e55-aa5b5b55b5a5", "buyeruid": "htrhr651615616d1h6", "at": 1, "imp": [ { "id": "555555555", "instl": 1, "secure": 0 } ], "site": { "id": "555555", "domain": "example.com", "cat": [ "IAB25-3" ], "page": "http://example.com", "ext": { "exchangecat": 555, "idzone": "5555335" } }, "device": { "ua": "Mozilla/5.0 (Linux; Android 10; M2006C3LG) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.120 Mobile Safari/537.36", "ipv6": "3b03:1756:ol1e:a100:1571:8bp1:f36:1d8f", "ifa": "5974d090-4516-4565-933d-69c79c9abf75", "geo": { "country": "UKR", "utcoffset": 7 }, "language": "ru", "os": "Android", "js": 1, "ext": { "remote_addr": "95.57.58.198", "x_forwarded_for": "" } }, "user": { "id": "55f7d5acada5b5.555555555555555555", "yob": 1990, "gender": "M", "ext": { "consent": "1" } }, "bcat": [ "IAB24", "IAB25", "IAB26" ], "badv": [ "example.com", "example.ru", "example.net" ] } |
PUSH
{ "id": "5", "at": 1, "cur": [ "USD" ], "tmax": 150, "imp": [ { "id": "5-5", "secure": 1, "bidfloor": 0.001, "bidfloorcur": "USD", "native": { "ver": "1.1", "request": "{\"ver\":\"1.1\",\"layout\":1,\"adunit\":2,\"plcmtcnt\":1,\"assets\":[{\"id\":5,\"required\": 1,\"title\":{\"len\":45}},{\"id\":2,\"required\":1,\"img\":{\"type\":1,\"wmin\":192,\"hmin\": 192,\"mimes\":[\"image/jpeg\",\"image/png\"]}},{\"id\":3,\"required\":1,\"data\":{\"type\": 2,\"len\":40}},{\"id\":4,\"required\":0,\"img\":{\"type\":3,\"wmin\":360,\"hmin\":240, \"mimes\":[\"image/jpeg\",\"image/png\"]}},{\"id\":5,\"required\":0,\"data\":{\"type\":12}}, {\"id\":6,\"required\":0,\"data\":{\"type\":12}}],\"plcmttype\":4}" } "ext": { "subage": 2} ], "site": { "id": "5", "domain": "example.com", "page": "https://example.com/ru/", "name": "exmp-1", "publisher": { "id": "5" }, "cat": [ "IAB3-1" ] }, "device": { "ip": "127.1.0.0", "ifa": "5974d090-4516-4565-933d-69c79c9abf75", "ua": "Mozilla/5.0 (Linux; Android 9; Redmi 6A) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Mobile Safari/537.36", "geo": { "country": "AT", "utcoffset": 7 } }, "user": { "id": "Xef5LfyUte-tzwpV5-fMV", "yob": 1990, "gender": "M", "ext": { "consent": "1" } }, "bcat": [ "IAB24", "IAB25", "IAB26" ], "badv": [ "example.com", "example.ru", "example.net" ] } |
ON SITE PUSH (INPAGE)
{ "id": "5", "at": 1, "cur": [ "USD" ], "tmax": 150, "imp": [ { "id": "5-5", "secure": 1, "bidfloor": 0.001, "bidfloorcur": "USD", "native": { "ver": "1.1", "request": "{\"assets\":[{\"title\":{\"len\":50},\"id\":5,\"required\":1},{\"id\":2,\"img\": {\"w\":200,\"hmin\":200,\"type\":3,\"wmin\":200,\"h\":200},\"required\":1}],\"ver\":1.1}" } ], "site": { "id": "5", "domain": "example.com", "page": "https://example.com/ru/", "name": "exmpl-5", "publisher": { "id": "5" }, "cat": [ "IAB3-1" ] }, "device": { "ip": "127.1.0.0", "ifa": "5974d090-4516-4565-933d-69c79c9abf75", "ua": "Mozilla/5.0 (Linux; Android 9; Redmi 6A) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Mobile Safari/537.36", "geo": { "country": "AT", "utcoffset": 7 } }, "user": { "id": "Xef5LfyUte-tzwpV5-fMV", "yob": 1990, "gender": "M", "ext": { "consent": "1" } }, "bcat": [ "IAB24", "IAB25", "IAB26" ], "badv": [ "example.com", "example.ru", "example.net" ] } |
NATIVE (TEASER)
{ "id": "5", "at": 1, "cur": [ "USD" ], "tmax": 150, "imp": [ { "id": "5-5", "secure": 1, "bidfloor": 0.001, "bidfloorcur": "USD", "tagid": "123123-123", "instl": 0, "native": { "ver": "1.1", "request": "{\"assets\":[{\"title\":{\"len\":50},\"id\":5,\"required\":1},{\"id\":2,\"img\": {\"w\":200,\"hmin\":200,\"type\":3,\"wmin\":200,\"h\":200},\"required\":1}],\"plcmtcnt\":8}" } ], "site": { "id": "5", "domain": "example.com", "page": "https://example.com/ru/", "name": "exmpl-5", "publisher": { "id": "5" }, "cat": [ "IAB3-1" ] }, "device": { "ip": "127.1.0.0", "ifa": "5974d090-4516-4565-933d-69c79c9abf75", "ua": "Mozilla/5.0 (Linux; Android 9; Redmi 6A) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Mobile Safari/537.36", "geo": { "country": "AT", "utcoffset": 7 } }, "user": { "id": "Xef5LfyUte-tzwpV5-fMV", "yob": 1990, "gender": "M", "ext": { "consent": "1" } }, "ext": { "bsection": [ 1001 ], "btags": [ 16, 14, 4 ] }, "bcat": [ "IAB24", "IAB25", "IAB26" ], "badv": [ "example.com", "example.ru", "example.net" ] } |
NATIVE APP
{ "at": 2, "cur": [ "USD" ], "device": { "devicetype": 4, "geo": { "country": "UKR", "lat": 50.4522, "lon": 30.5287, "type": 2 }, "ip": "127.1.0.0", "js": 1, "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.1 Mobile/15E148 Safari/604.1", "language": "uk" }, "id": "e555e555-5bb5-55f5-55ce-555faf555555", "imp": [ { "tagid": "5553", "bidfloor": 0.01, "bidfloorcur": "USD", "id": "fec5a5a555", "native": { "request": "{\"ver\":\"1.1\",\"plcmttype\":4,\"plcmtcnt\":2,\"assets\":[{\"id\":5,\"required\":1,\"title\":{\"len\":100}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":400,\"h\":400}},{\"id\":3,\"data\":{\"type\":2,\"len\":200}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}]}", "ver": "1.1" }, "secure": 1 } ], "site": { "cat": [ "IAB12", "IAB12-1", "IAB12-2", "IAB12-3" ], "domain": "example.com", "id": "5555", "name": "example.com", "page": "https://www.example.com/", "Content": {} }, "tmax": 500, "user": { "id": "5f5ab5ca-5555-55a5-555f-d5f5f5c55555" }, "ext": { "audit": { "id": 5 }, "shown": null, "reload_count": 0 }, "bcat": [ "IAB24", "IAB25", "IAB26" ], "badv": [ "example.com", "example.ru", "example.net" ] } |
BANNER
{ "id": "5", "at": 1, "cur": [ "USD" ], "tmax": 150, "imp": [ { "id": "5-5", "secure": 1, "bidfloor": 0.001, "bidfloorcur": "USD", "banner": { "w": 640, "h": 360, "format": [ { "w": 300, "h": 50 }, { "w": 468, "h": 60 } ] }, "instl": 0, "tagid": "123123-123" } ], "site": { "id": "5", "domain": "example.com,", "page": "https://example.com,/ru/", "name": "exmpl-5", "publisher": { "id": "5" }, "cat": [ "IAB3-1" ] }, "device": { "ip": "127.1.0.0", "ifa": "5974d090-4516-4565-933d-69c79c9abf75", "ua": "Mozilla/5.0 (Linux; Android 9; Redmi 6A) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Mobile Safari/537.36", "geo": { "country": "AT", "utcoffset": 7 } }, "user": { "id": "Xef5LfyUte-tzwpV5-fMV", "yob": 1990, "gender": "M", "ext": { "consent": "1" } }, "bcat": [ "IAB24", "IAB25", "IAB26" ], "badv": [ "example.com", "example.ru", "example.net" ] } |
BANNER APP
{ "id": "b5b555f555f555a5", "imp": [ { "id": "5", "banner": { "format": [ { "w": 320, "h": 50 } ], "w": 320, "h": 50, "battr": [ 6, 7 ], "api": [ 3, 5, 7 ] }, "bidfloor": 0.004724, "bidfloorcur": "USD", "secure": 1 } ], "app": { "id": "555555555", "name": "Example", "bundle": "5555555555", "domain": "example.com", "storeurl": "https://apps.apple.com/us/app/example/id555555555?uo=4", "cat": [ "IAB1-6" ], "ver": "3.1", "publisher": { "id": "555555555", "name": "Ivan Ivanov" } }, "device": { "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148", "geo": { "type": 2, "country": "DEU", "region": "NW", "city": "Bielefeld", "zip": "33602" }, "dnt": 1, "lmt": 1, "ip": "127.1.0.0", "devicetype": 4, "make": "apple", "model": "iphone", "os": "iOS", "osv": "14", "js": 1, "language": "en", "carrier": "Exfone Pable", "connectiontype": 2 }, "user": { "ext": { "consent": "1" } }, "at": 1, "tmax": 586, "cur": [ "USD" ], "regs": { "coppa": 0, "ext": { "gdpr": 1 } }, "badv": [ "example.com", "example.ru", "example.net" ] } |
VIDEO
{ "id": "5", "at": 1, "cur": ["USD"], "tmax": 200, "imp": [ { "id": "5-5", "secure": 1, "bidfloor": 0.001, "bidfloorcur": "USD", "tagid": "video-300x250", "video": { "mimes": ["video/mp4", "video/webm"], "minduration": 1, "maxduration": 60, "minbitrate": 700, "maxbitrate": 1500, "protocols": [2, 3, 5, 6, 7, 8], "w": 640, "h": 360, "startdelay": 0, "linearity": 1, "playbackmethod": [1, 2], "delivery": [2], "api": [1, 2], "pos": 1, "companiontype": [1, 2] }, "instl": 0 } ], "site": { "id": "5", "domain": "example.com", "page": "https://example.com/ru/", "publisher": {"id": "5"}, "cat": ["IAB3-1"] }, "device": { "ip": "127.1.0.0", "ua": "Mozilla/5.0 (Linux; Android 9; Redmi 6A) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Mobile Safari/537.36", "language": "en", "geo": { "country": "AUT", "utcoffset": 7 } }, "user": { "id": "Xef5LfyUte-tzwpV5-fMV" }, "bcat": ["IAB24", "IAB25", "IAB26"], "badv": ["example.com"] } |
OpenRTB Bid Response
OpenRTB Bid Response
Описание поддерживаемых параметров
Параметр | Описание | Использование | Обязательный |
id | ID bid request |
|
|
cur | Валюта ставки (с использованием ISO-4217) |
|
|
seatbid | Массив seatbid объектов |
|
|
seatbid
Параметр | Описание | Использование | Обязательный |
bid | Массив bid объектов |
|
|
seat | ID покупателя, от имени которого делается ставка |
|
|
group | 0 = можно выиграть в индивидуальном порядке; 1 = должны быть выиграны или проиграны группой | По умолчанию 0 |
|
seatbid.bid
Параметр | Описание | Использование | Обязательный |
id | ID ставки |
|
|
crid (adid, cid) | идентификатор креатива | Помогает в проверке качества рекламы | да |
impid | ID объекта Imp в соответствующем запросе ставки |
|
|
dealid | ID приватной сделки (Deal) | Заполняется только в Private Marketplace / Direct Deals | Опциональный |
language | Язык креатива (ISO-639-1) | Для проверки соответствия языку страницы паблишера | Опциональный |
price | Цена предложения, выраженная как CPM |
|
|
nurl | URL уведомление о выигрыше | Вызывается в случае выигрыша ставки |
|
burl | URL биллинг-уведомление | Если партнер поддерживает burl, то для его включения необходимо обратиться к менеджеру. По умолчанию отсутствует |
|
lurl | URL уведомление о проигрыше | Вызывается SSP, когда известно, что ставка была проиграна. Прежде чем включить передачу lurl, необходимо обсудить с менеджером Kadam реакции на коды. Возможные реакции: бан для tagid, site.domain, site.id, целиком для интеграции. |
|
adomain | Домен рекламодателя для проверки списка блоков (например, "ford.com") | Это может быть массив для случая ротации креативов. Биржи могут установить, что разрешен только один домен |
|
cat | IAB категория креатива |
|
|
adm | Средство передачи рекламной разметки в случае выигрыша ставки | Для видео — VAST XML, может содержать <CompanionAds> с <StaticResource> для показа баннера-компаньона рядом с плеером | Опциональный |
w | Ширина креатива в независимых от устройства пикселях | Используется по умолчанию при ответе баннером |
|
h | Высота креатива в независимых от устройства пикселях | Используется по умолчанию при ответе баннером |
|
Поддержка VAST Wrapper Если в bid.adm приходит VAST с тегом <Wrapper> вместо <InLine>, Kadam поддерживает два режима обработки (выбирается на стороне Kadam при подключении интеграции):
Passthrough (по умолчанию) — Kadam пробрасывает Wrapper VAST как есть в ответ паблишеру, добавляя свои tracking-пиксели. Резолвить цепочку до InLine будет плеер на стороне паблишера.
Resolve — Kadam сам разворачивает цепочку Wrapper'ов до InLine, делая HTTP-запросы по VASTAdTagURI, и собирает все tracking/click-tracking из промежуточных Wrapper'ов в финальный VAST.
Максимальная глубина цепочки: 5 редиректов.
Таймаут на резолв: 30% от tmax (минимум 500 мс, максимум 2 с).
HTTP-редиректы 301/302/303/307/308 поддерживаются (до 5 на одну ноду цепочки).
User-Agent при запросе: SSP/1.0.
Чтобы переключить режим, обратитесь к менеджеру.
Tracking events В <TrackingEvents> Kadam пробрасывает следующие события (режим InLine):
start
firstQuartile
midpoint
thirdQuartile
complete
В режиме Wrapper (passthrough) дополнительно пробрасываются: creativeView, mute, unmute, pause, resume, rewind, skip, playerExpand, playerCollapse, closeLinear, progress, loaded.
События за пределами этого списка из Wrapper-VAST'a будут проигнорированы.
Подстановка макросов в nurl/lurl/burl В URL nurl/lurl/burl Kadam ожидает следующие подстановки (заменяются Kadam при отправке нотификации):
${AUCTION_PRICE}— финальная цена клиринга (CPM)${AUCTION_CURRENCY}— валюта аукциона (USD)${AUCTION_BID_ID}— ID ставки (seatbid.bid.id)${AUCTION_ID}— ID аукциона (BidRequest.id)${AUCTION_IMP_ID}— ID показа (imp.id)${AUCTION_LOSS}— для lurl: код причины проигрыша по OpenRTB 2.5
Пример:
https://dsp.example.com/nurl?bid=${AUCTION_PRICE}&cur=${AUCTION_CURRENCY}Loss Reason Codes (для ${AUCTION_LOSS}, OpenRTB 2.5 §5.24):
1 — Internal Error
2 — Impression Opportunity Expired
3 — Invalid Bid Response
4 — Invalid Deal ID
5 — Invalid Auction ID
6 — Invalid Advertiser Domain
100 — Creative Filtered: General
101 — Creative Filtered: Pending Processing
102 — Creative Filtered: Disapproved
103 — Creative Filtered: Size Not Allowed
1001 — Lost to Higher Bid
1002 — Lost to Bid Below Auction Floor
1003 — Lost to Bid Below Deal Floor
Примеры Bid Response
POPS
PUSH
ON SITE PUSH (INPAGE)
NATIVE (TEASER)
NATIVE APP
BANNER
BANNER APP
{ "cur": "USD", "id": "th5qj5l5tp5sbjg55t5", "seatbid": [ { "bid": [ { "id": "5", "crid": "TPL55_AD4921726", "impid": "1", "price": 0.014145912714302543, "lurl": "https://example.com/lurl/830/nnbqypdkjerv4xtfhm5viiy2hy2qc4a5avceq72ymjewgyaokho72rlp6dy55d5ivxd3nfrtm3huswkufdvfiycibgaptd4ir7l7vneyheq77i4mzbgrdueixdjtgmpngpoe4kljv3fpqubainmdevspjnqva6auci4qd3jtezcteykqpbkfeofzk2zfotwdmbnoqvpzvba5sm54yvknsuocl6jdtn63tzkiesqys43g5bzzqwd7w2mxjlffnhkvki4esko2k5n3wycjqvksx7yhko7vi7kayjwnavlnrbegvcsxigbwau5ikvooashq5k2irmu6v6d2wu6yjdyovneiwkpk7b5lkpieq2gak5gb4mqu6flcgbkdx2isnktuznjhwaibpt4wxex4y2hztl4hvowttc3lffpu6s3bkb4fiutybbldraimyom5yryfki4es2jsk27xjkksdwdfaoernmz3mtmczguzwuv2hjbzsmcxyvegs2kjmiyfykypkthey2gbkp6fl6r3jlmtc47xjccniweukhtm2spckwf3h65gpoevcmu6jihkmtgvrtup6u6qhrhw2q77sbfgfqd43bikatlisjjntwv3257pyvrz7fwytrwbxsw2nqkw5i6otq53sk33jhvpq5kq====?1=1&data[]=16267695581629189819560392&v[]=1326260555&cur=${AUCTION_CURRENCY}&bid=${AUCTION_PRICE}&total=1.051696270431351&loss=${AUCTION_LOSS}", "adomain": [ "example.com" ], "cat": [ "IAB3-10" ], "adm": "<div id=\"EpLvPrThwzjHXYMe\"><a href=\"https://example.com/h/nodxsxhg65nhtcogyg6j3l4hvowts2osulmlrb4x5f5hyuyizfvquuqpoquvgkgcyprm4322gpluvx2w2bk2xpkb3ez6nwcj3fi7rvgsxd465ufhqffksulwrrjtxklihs7e5uvzwk723lohw2ldhjso2k43fp5nvxd3nfrt2zg6xs6zxswk3r5wsyz4mtkkyfjhf7sqhintzasulpzwgunvkzjdr2jj2jkfni3dooefmuoajnglevnkz5a5q64k2ymos2xwv3k32yx5pnpikg3vvey4rixt4zl2uv2uhq4mb3kxjsjwfxvczwcddklkxzkkosdaub5vlur4374orukj3nsvc2qnlldpxrjqi2s4c7sipf2fq6cihe4a4rjl3nnrbuctsbemfis675fjrvlqxrjzhwlbwjke5q3dv3fpquefjmipkgdvrzrzzfu5nxyexqruqngtfjq6ikyvacsczihkmtmp4pfkbcuf2comsm2mprawwpqqnuqfg6yflrqsow6t764jppf7zoe7qv3hzoi3z6k7aly6degrkal4xy74fi2nhgvfqxektmfutzivuus2xreftnsxm5evdrxjr3kt4432hjlvpyhrlbmk3vzqobutevspjnqvboa=?u=https%3A%2F%2Fexample.com.ru%2F%3Futm_source%3Dkad_tizer%26utm_campaign%3D509290%26utm_medium%3D1380663657990203%26utm_content%3D4921726\" trackerlink=\"https://example.com/c/nodxsxhg65nhtcogyg6j3l4hvowts2osulmlrb4x5f5hyuyizfvquuqpoquvgkgcyprm4322gpluvx2w2bk2xpkb3ez6nwcj3fi7rvgsxd465ufhqffksulwrrjtxklihs7e5uvzwk723lohw2ldhjso2k43fp5nvxd3nfrt2zg6xs6zxswk3r5wsyz4mtkkyfjhf7sqhintzasulpzwgunvkzjdr2jj2jkfni3dooefmuoajnglevnkz5a5q64k2ymos2xwv3k32yx5pnpikg3vvey4rixt4zl2uv2uhq4mb3kxjsjwfxvczwcddklkxzkkosdaub5vlur4374orukj3nsvc2qnlldpxrjqi2s4c7sipf2fq6cihe4a4rjl3nnrbuctsbemfis675fjrvlqxrjzhwlbwjke5q3dv3fpquefjmipkgdvrzrzzfu5nxyexqruqngtfjq6ikyvacsczihkmtmp4pfkbcuf2comsm2mprawwpqqnuqfg6yflrqsow6t764jppf7zoe7qv3hzoi3z6k7aly6degrkal4xy74fi2nhgvfqxektmfutzivuus2xreftnsxm5evdrxjr3kt4432hjlvpyhrlbmk3vzqobutevspjnqvboa=?u=https%3A%2F%2example.ru%2F%3Futm_source%3Dkad_tizer%26utm_campaign%3D509290%26utm_medium%3D1380663657990203%26utm_content%3D4921726\" data-set=\"href\" target=\"_blank\" class=\"k-bloc wzuRrdoPaKupOzsD\"><div class=\"k-bloc__age\">12+</div><div class=\"k-bloc__img\" style=\"background-image: url('https://example.com/auto/300x194/image/tesr/1726/726/rect_60e3140b614cat1625494539r8069.jpg');\"></div><div class=\"k-bloc__btnwrap\"><div class=\"k-bloc__btn\"><div>Самые милые котята!</div><div class=\"k-bloc__domain\">example.ru</div><div class=\"k-bloc__disclaimer\"></div></div><div class=\"k-bloc__arrow\"><svg width=\"30\" height=\"18\" viewBox=\"0 0 30 18\" fill=\"none\" xmlns=\"http://www.example.com/2000/svg\"><path d=\"M3 9L27 9\" stroke=\"white\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/><path d=\"M22.5 4.5L27 9L22.5 13.5\" stroke=\"white\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/></svg></div></div></a></div><style>#EpLvPrThwzjHXYMe * {box-sizing: border-box;font-family: Arial, sans-serif}#EpLvPrThwzjHXYMe .k-bloc {position: relative;width: 300px;height: 250px;display: block;background-color: #fff}#EpLvPrThwzjHXYMe .k-bloc:hover .k-bloc__btnwrap {bottom: 32px}#EpLvPrThwzjHXYMe .k-bloc__img {height: 194px;width: 300px;background-position: center;background-repeat: no-repeat;background-size: cover;overflow: hidden;}#EpLvPrThwzjHXYMe .k-bloc__text {font-weight: 400;position: absolute;bottom: 5px;left: 18px;max-width: 265px;font-size: 8px;line-height: 9px;color: #b4b4b4;height: 18px;overflow: hidden}#EpLvPrThwzjHXYMe .k-bloc__btnwrap {position: absolute;bottom: 27px;left: 8px;display: flex;justify-content: space-between;align-items: flex-end;width: 284px;box-sizing: border-box;text-decoration: none;transition: all .2s;background-color: #4f4f4f;box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);border-radius: 5px;padding: 12px 8px 12px 12px}#EpLvPrThwzjHXYMe .k-bloc__btn {width: 220px;font-size: 14px;line-height: 16px;color: #fff;font-weight: 700;margin-right: 4px;box-sizing: border-box;transition: all .2s}#EpLvPrThwzjHXYMe .k-bloc__arrow {margin-bottom: -4px;width: 30px;height: 18px;display: flex;justify-content: center;align-items: center;box-sizing: border-box;transition: all .2s}#EpLvPrThwzjHXYMe .k-bloc__arrow svg {width: 100%;height: 100%}#EpLvPrThwzjHXYMe .k-bloc__domain {font-size: 12px;line-height: 14px;color: #69c0ff;margin-top: 8px;margin-bottom: 3px;}#EpLvPrThwzjHXYMe .k-bloc__age {width: 24px;height: 24px;left: 8px;top: 8px;position: absolute;display: flex;justify-content: center;align-items: center;font-weight: bold;font-size: 10px;line-height: 12px;color: gray;background-color: #fcfcfc;opacity: .75;border-radius: 2px}#EpLvPrThwzjHXYMe .k-bloc__disclaimer {font-size: 7px;line-height: 8px;color: #B4B4B4;}</style>" } ], "seat": "1", "group": 0 } ] } |
VIDEO (InLine VAST)
{ "id": "5", "cur": "USD", "seatbid": [ { "bid": [ { "id": "1", "crid": "5555555", "impid": "5-5", "price": 2.5, "nurl": "https://dsp.example.com/nurl?bid=${AUCTION_PRICE}&cur=${AUCTION_CURRENCY}", "lurl": "https://dsp.example.com/lurl?loss=${AUCTION_LOSS}", "adomain": ["example.com"], "cat": ["IAB1"], "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"3.0\"><Ad id=\"item_0\"><InLine><AdSystem><![CDATA[KDM]]></AdSystem><AdTitle><![CDATA[Заголовок ролика]]></AdTitle><Impression><![CDATA[https://dsp.example.com/imp]]></Impression><Creatives><Creative sequence=\"1\"><Linear skipoffset=\"00:00:05\"><Duration>00:00:30</Duration><TrackingEvents><Tracking event=\"start\"><![CDATA[https://dsp.example.com/tr/start]]></Tracking><Tracking event=\"firstQuartile\"><![CDATA[https://dsp.example.com/tr/q1]]></Tracking><Tracking event=\"midpoint\"><![CDATA[https://dsp.example.com/tr/mid]]></Tracking><Tracking event=\"thirdQuartile\"><![CDATA[https://dsp.example.com/tr/q3]]></Tracking><Tracking event=\"complete\"><![CDATA[https://dsp.example.com/tr/done]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[https://example.com/landing]]></ClickThrough><ClickTracking><![CDATA[https://dsp.example.com/ct]]></ClickTracking></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" bitrate=\"915\" width=\"1280\" height=\"720\"><![CDATA[https://example.com/video.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives></InLine></Ad></VAST>" } ], "seat": "1", "group": 0 } ] } |
VIDEO (VAST with Companion Ads)
<!--?xml version="1.0" encoding="UTF-8"?-->
<!--[CDATA[KDM]]-->
<!--[CDATA[Заголовок ролика]]-->
<!--[CDATA[https://example.com/nurl/...]]-->
00:00:30
<!--[CDATA[https://...]]-->
<!--[CDATA[https://...]]-->
<!--[CDATA[https://...]]-->
<!--[CDATA[https://...]]-->
<!--[CDATA[https://...]]-->
<!--[CDATA[https://example.com/click/...]]-->
<!--[CDATA[https://example.com/ct/...]]-->
<!--[CDATA[https://example.com/video/video.mp4]]-->
<!--[CDATA[https://example.com/companion/banner.png]]-->
<!--[CDATA[https://example.com/click/...]]-->
<!--[CDATA[https://example.com/ct/...]]-->
<!--[CDATA[https://example.com/cv/...]]-->