Overview
Integration
Find out about integration with Feed and OpenRTB here:
Bid Request/Response
Bid Request/Response Specifications and Examples are here:
Integration process
1. Documentation review.
2. DSP creates and outputs an endpoint/feed for the appropriate ad format and integration type.
3. Tests are conducted to make sure that the integration works and that there is a discrepancy between the Kadam system and DSP.
4. If the discrepancies between the system data are within normal limits and there are no technical problems, the integration starts in full working mode.
Key points
Kadam supports Feed, OpenRTB 2.5, Native 1.1, Native 1.2 protocols;
In order to connect a new DSP, you must make sure that you support the transmission of the necessary parameters and are ready to send requests and receive responses from us;
The document specifies the parameters supported by Kadam, if any parameters are not described, it means that their support is not realized.
Cookie Matching
Cookie Matching is a feature that enables you to match your cookie, for example, an ID for a user that browsed your website, with the corresponding Kadam user ID. For this matching to happen, the SSP or DSP needs to be proactive and show the DMP pixel to the partner. The purpose of showing the partner's pixel is to pass the user ID on its version and keep the link in the mapping table. The custodians can be: SSP, DSP, both.
To configure Cookie Matching, you must contact the Kadam manager.
Feed Integration
Feed Integration
This documentation explains how DSP can integrate their platforms with Kadam using the Feed standard.
Bid Request/Response
Supported ad types:
Native;
Push;
On site push (inpage);
iOS calendar push;
Pops.
Feed Bid Request
Feed Bid Request
Description of supported parameters
These objects should be sent in GET request parameters:
Attribute | Description | Using | Always passed |
sid | endpoint ID | Stream uniqueness in Kadam. Issued by Kadam | Yes |
skey | API key | Issued by Kadam |
|
ua | user agent | To identify the user's operating system, device and browser on the Kadam side | Yes |
ip | User’s IP address | To determine the geolocation of a user's device on the Kadam sidem | Required ip or ipv6 |
uid | User ID in the SSP | For user uniqueness | Yes |
limit | Limiting the number of creatives in a response | If there is no limit in the request and on the block, the default=1 |
|
language | Main browser language, ISO 3166-1 alpha-2 coding | To define the browser language. Examples: &language=ru-RU or &language=ru. If the parameter "language" is not filled in, filled in incorrectly or not passed, it is considered "undefined", it reduces the buyout |
|
subage / subage_dt / subage0 / subage_ts | User subscription age | If the "subage" parameter is not filled in, filled in incorrectly, or not passed, it is considered "undefined", this reduces the buyout. For the first day of subscription expected: subage=1, subage0=0, subage_dt - actual date of subscription, subage_ts - actual date of subscription (unixtime) | Yes |
pid | Publisher ID | This parameter expects the ID of the publisher (site, webmaster) on the SSP | Yes |
cat | IAB-category domain | IAB24 on meinstream and IAB25-3 on adalt by default | No |
page | Page domain | Expected page domain | Desirable |
format | Traffic format | cu, pops - for pops; native, teaser - for teaser; push by default | No |
Examples of 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
Description of supported parameters (to change the naming of parameters in Bid Response please contact our manager)
Attribute | Description | Using | Always passed |
id | Material ID |
|
|
impid | Impression ID |
|
|
crid (adid, cid) | Creativity ID |
| yes |
nurl | URL notification of win | It is possible to send: As a nurl, As part of an icon_url, As part of the image_url. |
|
link (click_url) | Clickable link |
| yes |
campaing_id (cid) | Campaign ID |
|
|
category | Material category (section) ID |
|
|
title | Ad title |
| yes |
description (desc) | Header ad |
|
|
text | Ad text |
|
|
image_url | Link to material image |
| yes |
icon_url | Icon link + nurl | Used in push notifications |
|
cpc (price, bid) | Bid price |
| yes |
image | Link to image + nurl |
|
|
result | Bid objects | Used in pops |
|
listing | Array of bid objects |
|
|
result.listing
Attribute | Description | Using | Alwayas passed |
url | Clickable link |
|
|
bid | Bid |
|
|
Examples of Bid Response:
PUSH
1 icon_url contains nurl and icon_url
2 with “nurl”
POPS
ON SITE PUSH (INPAGE)
IOS CALENDAR PUSH
1
2
NATIVE
OpenRTB Integration
OpenRTB Integration
This documentation explains how DSP can integrate their platforms with Kadam using the OpenRTB standard.
Bid Request/Response
Supported ad types:
Native;
Native (teaser);
Banner;
Video;
Push;
On site push (inpage);
iOS calendar push;
Pops (Clickunder).
Integration with banner DSP
For correct display of clicks in our statistics, please pass the following in the "adm" parameter:
1 option (preferred)
Click macros: ${CLICK_URL};
Your clickable link in URL-endcode format.
For example, your clickable link is "http://example.ru". In that case you should pass it as "${CLICK_URL}http%3A%2F%2Fexample.ru", where we replace the macros with our clickable link, the user will get to us first and then we redirect them via the endcode link that came after the macros to you.
2 option
Click macros:${CLICK_URL_ENC}.
In this case we will replace the macros with our endcode-click link. The user first gets to you and then you redirect to us using the link we replaced instead of the macros. An example is "http://example.com/example...${CLICK_URL_ENC}".
OpenRTB Bid Request
OpenRTB Bid Request
Description of supported parameters
These objects should be sent using JSON in the Request Body:
Attribute | Description | Using | Always passed |
id | Unique ID of the bid request, provided by the exchange |
| Yes |
at | Auction type. For SSPs that work by CPC, there is always an auction of the first price | For the first price auction at=1. Default 2 - Second Price | No |
cur | Auction currency. Valid values: USD - American dollar | Default - SSP currency | No |
imp | Array of objects: requirements for ad materials for placement | Used to select materials that are relevant to the requirements | Yes |
site | Details about the publisher's website |
| Required site or app |
app | Details about the publisher's app |
| Required site or app |
user | Details about the human user of the device |
| Yes |
badv | List of domains to be excluded from the auction |
| No |
bcat | Blocked categories of advertisers using IAB content categories |
|
|
device | Details about the user's device to which the impression will be delivered |
| Yes |
imp
Attribute | Description | Using | Always passed |
id | A unique identifier for this impression |
| Yes |
secure | Connection type. Possible choices: 0 - indicates that you should select materials available via http and https protocols. 1 - specifies that you should select only those materials that are available via https | Default value - https | No |
bidfloor | Minimum bid for this impression | Default 0 | No |
bidfloorcur | Impression value currency | Default - USD. Currency specified using ISO-4217 alpha codes | No |
tagid | Identifier for specific ad placement or ad tag that was used to initiate the auction |
| Recommended |
ext | Additional parameters |
|
|
native | Parameter for native and push formats, where you need to transmit assets (headers, descriptions, pictures, icons, etc.) |
| Required for Native, Push |
banner | Parameter for Banner format |
| Yes for Banner Ad |
video | Parameter for Video format |
| Required for Video Ad |
instl | Valid values: 1 - full-screen ad (interstitial), 0 - not interstitial | Default 0 | No |
battr | Blocked parameters |
| No |
imp.ext
Attribute | Description | Using | Always passed |
subage / subage_dt / subage0 / subage_ts | User subscription age | If the "subage" parameter is not filled in, filled in incorrectly, or not passed, it is considered "undefined", this reduces the buyout. For the first day of subscription expected: subage - 1, subage0 - 0, subage_dt - actual date of subscription, subage_ts - actual date of subscription (unixtime) | Yes for push Ad |
imp.native
Attribute | Description | Using | Always passed |
request | Request in JSON encoding for push and native materials | Options: openrtb.native.string - JSON query text; openrtb.native - the query is a JSON object. It is similar to openrtb.native.string, only in case of string query is encoded to JSON text | Yes |
ver | Version of the Native Ad Specification to which request complies |
|
|
imp.native.request
Attribute | Description | Using | Always passed |
plcmtcnt | The number of identical placements in this Layout |
|
|
imp.banner
Attribute | Description | Using | Always passed |
w | Width in device independent pixels (DIPS) |
| Required “w” and “h” or “format |
h | Height in device independent pixels (DIPS) |
| Required “w” and “h” or “format |
format | Array of Format objects representing the banner sizes permitted |
| Required “w” and “h” or “format” |
imp.video
Attribute | Description | Using | Always passed |
mimes | Whitelist of media-file MIME types. Example: ["video/mp4", "video/webm"] |
| Yes |
minduration | Minimum video duration, in seconds |
| Recommended |
maxduration | Maximum video duration, in seconds |
| Recommended |
protocols | Array of supported VAST versions (see enum below) |
| Yes |
w | Player width in pixels |
| Recommended |
h | Player height in pixels |
| Recommended |
startdelay | Delay before start, in seconds. 0 = pre-roll, -1 = mid-roll, -2 = post-roll |
| No |
linearity | 1 = Linear / in-stream, 2 = Non-linear / overlay |
| No |
api | Array of supported API frameworks (see enum below) |
| No |
minbitrate | Minimum acceptable MediaFile bitrate, kbps | Used when selecting the media file | No |
maxbitrate | Maximum acceptable MediaFile bitrate, kbps | Used when selecting the media file | No |
pos | Player position on the page: 0 = Unknown, 1 = Above the Fold, 3 = Below the Fold, 4 = Header, 5 = Footer, 6 = Sidebar, 7 = Full Screen |
| No |
playbackmethod | Array of autoplay methods: 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 |
| No |
delivery | Array of supported delivery types: 1 = streaming, 2 = progressive, 3 = download |
| No |
companiontype | Array of companion types: 1 = Static Resource, 2 = HTML Resource, 3 = iFrame Resource | If the player can display companion ads | No |
Enum for protocols (the Kadam parser supports 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 for api:
1 — VPAID 1.0
2 — VPAID 2.0
3 — MRAID-1
4 — ORMMA
5 — MRAID-2
6 — MRAID-3
7 — OMID-1
site
Attribute | Description | Using | Always passed |
id | Site ID on the exchange | For the uniqueness of the site, the creation of black- or white-lists | Yes |
domain | Domain of the site | For internal classification of domains in the Kadam system | Yes |
page | URL of the page where the impression will be shown | For internal classification of domains in the Kadam system | Recommended |
name | Stream name or its unique identifier |
|
|
publisher | Details about the Publisher object of the site |
|
|
content | Details about the Content within the site |
|
|
cat | Array of IAB content categories of the site | You don't have to pass it if the "domain" parameter is filled in, because Kadam classifies domains internally | Recommended |
ext | Additional site parameters |
|
|
site.publisher
Attribute | Description | Using | Always passed |
id | Unique ID of the site owner |
|
|
app
Attribute | Description | Using | Always passed |
id | Application ID on the exchange | For the uniqueness of the site, the creation of black- or white-lists | Yes |
domain | Domain of the application, used for advertiser side blocking. For example, “Foo.com” | For internal classification of domains in the Kadam system | Yes |
page | Full URL | For internal classification of domains in the Kadam system |
|
name | Application name (may be aliased at publisher's request) |
|
|
bundle | A platform-specific application identifier intended to be unique to the app and independent of the exchange. Examples: IOS - 1453331063 Android - com.foo.mygame |
|
|
storeurl | App store URL for an installed app |
|
|
cat | IAB site category | It is possible not to pass, if the parameter "domain" is filled in (Kadam has an internal classification of domains) | Recommended |
ver | The version of the native ad specification to which the request corresponds |
|
|
publisher | Details about the Publisher object of the app |
|
|
ext | Additional application parameters |
|
|
app.publisher
Attribute | Description | Using | Always passed |
id | Unique ID of the application owner |
|
|
name | Publisher name |
|
|
user
Attribute | Description | Using | Always passed |
id | Unique user ID in system | Kadam generates on its own if not filled in |
|
buyeruid | Unique user ID in the Kadam system | Used if Cookie Matching is configured. Is prioritized over user.id |
|
yob | Year of birth as a 4-digit integer |
|
|
Gender | Пол | "M" = male; "F" = female; "O" = unknown |
|
ext | Additional user parameters |
|
|
user.ext
Attribute | Description | Using | Always passed |
consent | The web-safe base64-encoded IAB Transparency and Consent Framework (TCF) v2 consent string fetched from the publisher's IAB Consent Management Platform (CMP). The structure of the string is defined by the IAB TCF v2 | This field will be populated if the publisher has integrated with a CMP for TCF v2 and that CMP indicates that GDPR applies to this ad request and provides a valid consent string |
|
device
Attribute | Description | Using | Always passed |
ifa | The unique identifier of the device in UUID format | If available in request, used as user.id | No |
geo | Geolocation of the user device |
| No |
ip | IPv4 address closest to device | To determine the geolocation of a user's device on the Kadam side | Required ip or ipv6 |
ipv6 | IP address closest to device as IPv6 | To determine the geolocation of a user's device on the Kadam side | Required ip or ipv6 |
ua | User agent | To identify the user's operating system, device and browser on the Kadam side | Yes |
js | Support for JavaScript, where 0 - no, 1 - yes |
|
|
language | Main browser language, ISO-639-1-alpha-2 | To define the browser language. Examples: &language=ru-RU or &language=ru. If the parameter "language" is not filled in, filled in incorrectly or not passed, it is considered "undefined", it reduces the buyout |
|
device.geo
Attribute | Description | Using | Always passed |
utcoffset | Local time as the number +/- of minutes from UTC |
|
|
country | Country using ISO-3166-1 Alpha-3 |
|
|
ext
Attribute | Description | Using | Always passed |
bsection | Used to specify the categories of material that are not allowed within a given request. Integer view | For a complete list of categories, please contact your manager | No |
btags | Used to specify the categories of material that are not allowed within a given request. Integer view | For a complete list of categories, please contact your manager | No |
Examples 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" ] } |
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" ] } |
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" ] } |
OpenRTB Bid Response
OpenRTB Bid Response
Description of supported parameters
Attribute | Description | Using | Always passed |
id | ID bid request |
|
|
cur | Bid currency using ISO-4217 alpha codes |
|
|
seatbid | Array of Seatbid objects |
|
|
seatbid
Attribute | Description | Using | Always passed |
bid | Array of 1+ Bid objects each related to an impression |
|
|
seat | ID of the buyer seat on whose behalf this bid is made |
|
|
group | 0 = impressions can be won individually; 1 = impressions must be won or lost as a group | Default - 0 |
|
seatbid.bid
Attribute | Description | Using | Always passed |
id | ID of the bid request to which this is a response |
|
|
crid (adid, cid) | Creative ID to assist with ad quality checking |
| yes |
impid | ID of the Imp object in the related bid request |
|
|
dealid | Private deal ID | Populated only for Private Marketplace / Direct Deals | Optional |
language | Creative language (ISO-639-1) | Used to check that the creative language matches the publisher page language | Optional |
price | Bid price expressed as CPM |
|
|
nurl | Win notice URL called by the exchange if the bid wins |
|
|
burl | Billing notice URL | If the partner supports “burl”, you must contact your manager to enable it. It is not available by default |
|
lurl | Loss notice URL | Called by the exchange when a bid is known to have been lost. Before enabling the lurl pass, you should discuss reactions to the codes with your Kadam manager. Possible reactions: ban for tagid, site.domain, site.id, whole for integration. |
|
adomain | Advertiser domain for block list checking (e.g., "addomain.com") | This can be an array for the case of rotating creatives. Exchanges can mandate that only one domain is allowed |
|
cat | IAB content categories of the creative |
|
|
adm | Means of conveying ad markup in case the bid wins | For video — VAST XML; may contain <CompanionAds> with <StaticResource> to display a companion banner alongside the player | Optional |
w | Width of the creative in device independent pixels (DIPS) | Used by default in response (in banner format) |
|
h | Height of the creative in device independent pixels (DIPS) | Used by default in response (in banner format) |
|
VAST Wrapper support
If bid.adm contains a VAST with a <Wrapper> tag instead of <InLine>, Kadam supports two processing modes (selected on the Kadam side when the integration is connected):
Passthrough (default) — Kadam passes the Wrapper VAST as is to the publisher, adding its own tracking pixels. The chain to InLine is resolved by the player on the publisher side.
Resolve — Kadam itself unwinds the Wrapper chain down to InLine by making HTTP requests to VASTAdTagURI and collects all tracking / click-tracking from intermediate Wrappers into the final VAST.
Maximum chain depth: 5 redirects.
Resolve timeout: 30% of tmax (minimum 500 ms, maximum 2 s).
HTTP redirects 301/302/303/307/308 are supported (up to 5 per chain node).
User-Agent used for the request: SSP/1.0.
To switch the mode, contact your manager.
Tracking events
In <TrackingEvents> Kadam passes through the following events (InLine mode):
start
firstQuartile
midpoint
thirdQuartile
complete
In Wrapper mode (passthrough) the following events are additionally passed through: creativeView, mute, unmute, pause, resume, rewind, skip, playerExpand, playerCollapse, closeLinear, progress, loaded.
Events outside this list coming from a Wrapper VAST will be ignored.
Macro substitution in nurl/lurl/burl
In the nurl/lurl/burl URLs Kadam expects the following substitutions (Kadam replaces them when the notification is sent):
${AUCTION_PRICE}— final clearing price (CPM)${AUCTION_CURRENCY}— auction currency (USD)${AUCTION_BID_ID}— bid ID (seatbid.bid.id)${AUCTION_ID}— auction ID (BidRequest.id)${AUCTION_IMP_ID}— impression ID (imp.id)${AUCTION_LOSS}— for lurl: loss reason code per OpenRTB 2.5
Example:
https://dsp.example.com/nurl?bid=${AUCTION_PRICE}&cur=${AUCTION_CURRENCY}Loss Reason Codes (for ${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
Examples 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[Video title]]></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[Video title]]-->
<!--[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/...]]-->