SSP Banner AD. Request API
Chansup Yang
REQUEST
SSP DSP
MezzoMedia SSP uses HTTP HOST to create the objects defined below in JSON form to call the DSP interface.
The request object definition follow OPEN RTB 2.5 specification.
Request object
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | request unique ID |
| cur | string array | N | ISO-4217-alpha currency for auction. ex: “KRW” |
| test | integer | N | test mode - 1, real mode - 0, You cannot bid for a test auction. |
| site | object | Y | Refer to site object. |
| app | object | Y | Refer to app object. |
| device | object | Y | Refer to device object. |
| user | object | Y | Refer to user object. |
| imp | object array | Y | Refer to imp object. |
| at | integer | Y | 0 : fixed price, 1: first price, 2: second price |
| tmax | integer | Y | Maximum time (ms). |
| bcat | string array | N | Blocked advertiser categories using the IAB content categories. |
| badv | string array | N | Block list of advertisers by their domains |
| bapp | string array | N | Block list of applications by their bundle or package names |
| ext | object | N | Refer to ext object. |
Site
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | publisher ID |
| name | string | N | application name |
| domain | string | N | site domain |
| page | string | N | page url |
| ref | string | N | address of a page just before been to the current page |
| cat | string array | N | category |
| publisher | object | Y | Refer to publisher object. |
app
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | publisher ID |
| name | string | N | application name |
| bundle | string | Y | bundle name, package name |
| storeurl | string | N | app store URL |
| cat | string array | N | category |
| publisher | object | Y | Refer to publisher object. |
publisher
site / publisher
app / publisher
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | publisher ID |
| name | string | N | publisher name |
| domain | string | N | site domain |
| product_attr | string | N | ad product code 1: standard banner 2: interstitial |
device
| Field | Type | Required | Description |
|---|---|---|---|
| adid | string | Y | device ad id |
| make | string | Y | OS ex) iOS, Anroid |
| ua | string | Y | device User Agent |
| dnt | integer | N | location tracking enabled, [0 : enable 1 : disable] |
| ip | string | Y | IPV4 address |
| model | string | N | model name |
| os | string | Y | OS ex) iOS, Anroid |
| osv | string | Y | OS version ex) 8.1, 9.2 |
| js | integer | N | It is defined as 1 in RTB protocol. |
| ifa | string | Y | Apple IFA or Google ADID |
user
This is an extension field of MezzoMedia not found in the RTB protocol.
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | user unique ID |
imp
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | impression unique ID |
| bidfloor | float | Y | The minimum price that can be approved by bidding. ex)4.12 |
| bidfloorcur | string | Y | currency, ex) ‘KRW’ |
| secure | integer | Y | 0 : http, 1 : https |
| type | string | Y | BANNER |
| banner | object | Y | Refer to banner object. |
| instl | integer | Y | Indicates whether this is a interstitial ad. (default : 0) * 1 = the ad is interstitial or full screen * 0 = not interstitial. |
| displaymanager | string | Y | Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). |
| displaymanagerver | string | Y | Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). |
banner
imp / banner
| Field | Type | Required | Description |
|---|---|---|---|
| w | integer | Y | banner width size |
| h | integer | Y | banner height size |
ext
This is an extension field of MezzoMedia not found in the RTB protocol.
| Field | Type | Required | Description |
|---|---|---|---|
| price_type | integer | N | 0:CPM, 2: CPC |
| click_macro | integer | N | 1: You need to provide the macro $ {MEZZO_CLICK_URL} to receive click tracking inside the ADM in the DSP media. When a click is made in the DSP, you must generate a click url replaced with a macro. |
Request example (APP)
{
"id": "55d9d872-6129-497d-8187-46ffea622dbe$1278072412$KKHSVVWN",
"test": 1,
"cur": "USD",
"source": {
"ext": {
"schain": {
"ver": "1.0",
"nodes": [
{
"asi": "mman.kr",
"sid": "31998",
"rid": "55d9d872-6129-497d-8187-46ffea622dbe$1278072412$KKHSVVWN",
"hp": 1
}
],
"complete": 1
}
}
},
"regs": {
"ext": {
"us_privacy": "1---"
}
},
"tmax": 320,
"at": 2,
"imp": [
{
"tagid": "805013_com.test.mezzo",
"secure": 0,
"clickbrowser": 1,
"displaymanager": "ManSDK",
"displaymanagerver": "200",
"instl": 0,
"banner": {
"w": 320,
"h": 50,
"api": [
1,
2
]
},
"ext": {},
"bidfloorcur": "USD",
"bidfloor": 0.0008411677387431965,
"id": "166330331300"
}
],
"app": {
"publisher": {
"id": "31998",
"name": "31998_%EC%9D%B4%EA%B2%83%EC%9D%B4 %ED%85%8C%EC%8A%A4%ED%8A%B8",
"product_attr": 1
},
"id": "805013_com.test.mezzo",
"name": "805013_%EC%9D%B4%EA%B2%83%EC%9D%B4 %ED%85%8C%EC%8A%A4%ED%8A%B8",
"bundle": "com.test.mezzo",
"storeurl": "https://play.google.com/store/apps/details?id=com.mz.mezzomediaapp",
"cat": [
"IAB9"
]
},
"user": {
"id": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1"
},
"device": {
"geo": {
"country": "KOR"
},
"adid": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1",
"ifa": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1",
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 9; SM-G955N Build/PPR1.180610.011; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/105.0.5195.79 Mobile Safari/537.36",
"ip": "58.231.40.30",
"make": "samsung",
"os": "Android",
"osv": "9",
"model": "SM-G955N",
"language": "ko",
"js": 1,
"devicetype": 1,
"ext": {
"gain": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1"
}
},
"ext": {
"request_time": 1663303313,
"price_type": 0
}
}
Request example (WEB)
{
"id": "b2b7e6c7-585b-45de-b55a-f219611c3cc6$1277829435$KKHSVVWN",
"test": 1,
"cur": [
"USD"
],
"source": {
"ext": {
"schain": {
"ver": "1.0",
"nodes": [
{
"asi": "mman.kr",
"sid": "31998",
"rid": "b2b7e6c7-585b-45de-b55a-f219611c3cc6$1277829435$KKHSVVWN",
"hp": 1
}
],
"complete": 1
}
}
},
"regs": {
"ext": {
"us_privacy": "1---"
}
},
"tmax": 320,
"at": 2,
"imp": [
{
"tagid": "805013_com.test.mezzo",
"secure": 0,
"instl": 0,
"banner": {
"w": 320,
"h": 50,
"api": [
1,
2
]
},
"ext": {},
"bidfloorcur": "USD",
"bidfloor": 0.0008411677387431965,
"id": "166330623100"
}
],
"site": {
"publisher": {
"id": "31998",
"name": "31998_com.test.mezzo",
"domain": "com.test.mezzo",
"product_attr": 1
},
"id": "805013_com.test.mezzo",
"name": "805013_com.test.mezzo",
"domain": "com.test.mezzo",
"page": "http://mtagdev.mman.kr:9300/V2/banner_step2.html",
"ref": "http://mtagdev.mman.kr:9300/",
"mobile": 1,
"cat": [
"IAB9"
]
},
"user": {
"id": "4fbf0ac3-63bb-43c5-83ab-418ea1fe0a12"
},
"device": {
"geo": {
"country": "KOR"
},
"adid": "4fbf0ac3-63bb-43c5-83ab-418ea1fe0a12",
"ifa": "",
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 10; SM-G981B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Mobile Safari/537.36",
"ip": "203.248.117.195",
"make": "",
"os": "Android",
"osv": "",
"model": "",
"language": "ko",
"js": 1,
"devicetype": 1
},
"ext": {
"request_time": 1663306231,
"price_type": 0
}
}
RESPONSE
DSP SSP
DSP responds by including the objects defined below in HTTP body.
Object definitions follow the OPEN RTB 2.5 specification.
Bid Response
Response object in JSON format.
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | bid Request ID |
| bidid | string | Y | bid object ID |
| cur | string | Y | currency for bidding ex) KRD |
| seatbid | object array | Y | seatbid Object array. It will be needed 1+ for the bid. |
seatbid
| Field | Type | Required | Description |
|---|---|---|---|
| seat | string | Y | ID that manages bid information |
| bid | object array | Y | bid Object array. It will be needed 1+ for the bid. |
bid
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | ID that manages bid information |
| impid | string | Y | impression ID related to impression of bid request. The bid request impression object ID must match. |
| price | float | Y | bid price |
| cat | string array | Y | category |
| nurl | string | N | win notice URL Replace the win bidding price to {AUCTION_PRICE} macro and deliver it. |
| burl | string | N | Billing notice URL Replace the win bidding price to {AUCTION_PRICE} macro and deliver it. |
| lurl | string | N | Loss notice URL Replace the fail in bidding code to {AUCTION_LOSS} macro and deliver it. |
| adm | string (html) | Y | Refer to adm object |
| iurl | string | Y | impression image URL |
| adomain | string array | Y | Advertiser domain for block list checking. |
| cid | string | Y | advertiser campaign name / id |
| crid | string | Y | advertiser creative name / id |
| w | integer | Y | creative width size |
| h | integer | Y | creative height size |
| ext | object | Y | extension area |
adm
html with no new line character and no spaces
Bid response example
{
"id": "ece5c105-dd24-468f-8392-d624b8d49953",
"seatbid": [
{
"bid": [
{
"id": "58eb3071faff4576320e4fe9",
"impid": "149015951000",
"price": 50,
"cat": ["iab1", "iab2", "iab2"],
"nurl": "win url",
"adm": "<html>...</html>",
"iurl": "image.jpg",
"cid": "80",
"crid": "188",
"h": 50,
"w": 320,
"ext": {}
}
],
"seat": "dsp id"
}
],
"bidid": "dsp",
"cur": "KRW"
}
Bid response(noad) example
{
"id": "",
"seatbid": [],
"bidid": "mezzo",
"cur": "KRW"
}
SKAdNetwork Support(iOS14+)
This information is intended to support campaigns with SKAdNetwork enabled in iOS14 version or above.
| 1 | DSPs should register as an Ad Network to Apple’s SKAdNetwork API. (https://developer.apple.com/documentation/storekit/skadnetwork/registering_an_ad_network) |
| 2 | Supply your public key to Apple and set your postback urls. |
| 3 | Provide your SKAdNetwork ID to MezzoMedia Manager and MezzoMedia will get your SKAdNetwork ID(s) added to publishers’ info.plist. |
| 4 | If the DSP is responding with a SKAdNetwork enabled campaign, it should respond with SKAdNetwork ID and all relevant fields in the bid response. |
| 5 | Advertiser app should be registering its new users to SkAdNetwork via registerAppForAdNetworkAttribution() |
| 6 | DSPs should have an install tracking service to handle install data and signature from the SKAdNetwork postback. |
Bid Request (SKAdNetwork)
BidRequest / imp / banner / ext / skadn
This object will be populated if all conditions below are met.
| 1 | The DSP has at least one SKAdNetwork ID registered in the publisher’s info.plist. |
| 2 | The user’s device is operating on iOS14 or above. |
| 3 | The DSP is on MezzoMedia spec. |
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
| version | string | Y | Version of skadnetwork supported. Always “2.0” or higher. | “version”:”2.0” |
| sourceapp | string | Y | ID of publisher app in Apple’s App Store. Should match ‘BidRequest.app.bundle’ | “sourceapp”:”000000000” |
| skadnetids | string | Y | A subset of SKAdNetworkItem entries in the publisher app’s info.plist that are relevant to the DSP. | “skadnetids”:[“feyaarzu9v.skadnetwork”] |
SKAdNetwork Bid Request Example
{
"imp":[{
"ext": {
"skadn": {
"version": "2.0",
"sourceapp": "000000000",
"skadnetids": ["feyaarzu9v.skadnetwork", "8sRFag4vVC.skadnetwork"]
}
}
}]
}
Bid Response (SKAdNetwork)
BidResponse / imp / banner / ext / skadn
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
| version | string | Y | Version of SKAdNetwork desired. Must be 2.0 or above. | “version”:”2.0” |
| network | string | Y | Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request. | “network”:[“feyaarzu9v.skadnetwork”] |
| campaign | string | Y | Campaign ID compatible with Apple’s spec. As of 2.0, should be an integer between 1 and 100, expressed as a string. | “campaign”:”45” |
| itunesitem | string | Y | ID of advertiser’s app in Apple’s app store. Should match ‘Bidresponse.bid.bundle’ | “itunesitem”:”123456789” |
| nonce | string | Y | An id unique to each ad response. | “nonce”:”123b1a78-b5ef-98ad-1234-ab-c4effa00b8” |
| sourceapp | string | Y | ID of publisher’s app in Apple’s app store. Should match ‘BidRequest.imp.ext.skad.sourceapp’ 과 매칭 | “sourceapp”:”000000000” |
| timestamp | string | Y | Unix time in millis string used at the time of signature. | “timestamp”:”1234567890” |
| signature | string | Y | SKAdNetwork signature as specified by Apple. | “signature”:”ABCDEFGHijkl-lmb…” |
SKAdNetwork Bid Response Example
{
"seatbid": [{
"bid": [{
"ext": {
"skadn": {
"version": "2.0",
"network":"feyaarzu9v.skadnetwork",
"campaign":"45",
"itunesitem":"123456789",
"nonce":"123b1a78-b5ef-98ad-1234-ab-c4effa00b8",
"sourceapp":"000000000",
"timestamp":"1234567890",
"signature":"ABCDEFGHijkl-lmbKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg==""
}
}
}]
}]
}