DSP Banner AD. Delivery API
InJun Kim
API list
| Service | Ad product | Response format |
|---|---|---|
| TARGETPICK | standard banner interstitial squre and rectangle skyscraper leaderboard |
JSON |
Domain info
| Division | URL |
|---|---|
| test | Because of security policy, it is provided when test is conducting. |
| real | Because of security policy, it is provided when test is completed. |
Ad request
[2.0] {domain}/dsp.mezzo/?ssp_id={ssp_id}
Configure the following in the form of a JSON compliant with OPEN RTB 2.5 and call the above URL in POST format.
Currently, it is defined only for fixed-price trading in OPEN RTB 2.5 specification.
RTB (Real Time Bidding) will be updated in the future.
Request object
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | request unique ID |
| cur | string array | N | ISO-4217-alpha currency for auction. ex: “KRW”. |
| imp | object array | Y | Refer to imp object. |
| site | object | Y | Refer to site object. |
| app | object | Y | Refer to app object. |
| publisher | object | Y | Refer to publisher object. |
| device | object | Y | Refer to device object. |
| user | object | Y | Refer to user 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 |
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 |
| 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 |
Site
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | site ID |
| name | string | N | application name |
| domain | string | Y | 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 |
app
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | app 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
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Y | publisher ID |
device
| Field | Type | Required | Description |
|---|---|---|---|
| ua | string | Y | device User Agent |
| ip | string | Y | IPV4 address |
| model | string | N | model name |
| os | string | Y | iOS , Android, mobile_web, pc_web |
| osv | string | Y | OS version ex) 8.1, 9.2 |
| ifa | string | Y | Apple IFA or Google ADID |
| geo | object | N | ISO 3166-1 Alpha-3 is the country-specific code value specified in ISO 3166-1. |
user
| Field | Type | Required | Description |
|---|---|---|---|
| buyeruid | string | Y | Cookie matching id received from Mezzo |
Ad request example (APP)
{
"id": "req-12345-abcde",
"imp": [{
"id": "1",
"bidfloor": 0,
"secure": 0,
"bidfloorcur": "KRW",
"instl": 0,
"banner": {
"w": 320,
"h": 50,
"btype": [1, 3, 4]
}
}],
"app": {
"id": "g0r8k3u5",
"name": "test",
"bundle": "com.test",
"storeurl": "http://test.com",
"publisher": {
"id": "publisher_id"
},
"cat": ["IAB3"]
},
"device": {
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
"ip": "123.123.123.123",
"ifa": "2B2D9FE6-F84F-4A36-86AA-5C3769DD1082",
"os": "iOS",
"osv": "8.1",
"model": "iPhone6",
"geo":{"country":"KOR"}
},
"user": {
"buyeruid": "923123"
}
}
Ad request example (web)
{
"id": "req-12345-abcde",
"imp": [{
"id": "1",
"bidfloor": 0,
"secure": 0,
"bidfloorcur": "KRW",
"instl": 0,
"banner": {
"w": 320,
"h": 50,
"btype": [1, 3, 4]
}
}],
"site": {
"id": "g0r8k3u5",
"name": "test",
"site": "gamefocus.co.kr",
"page": "http://gamefocus.co.kr",
"ref": "http://www.naver.com",
"publisher": {
"id": "publisher_id"
},
"cat": ["IAB3"]
},
"device": {
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
"ip": "123.123.123.123",
"ifa": "2B2D9FE6-F84F-4A36-86AA-5C3769DD1082",
"os": "iOS",
"osv": "8.1",
"model": "iPhone6",
"geo":{"country":"KOR"}
},
"user": {
"buyeruid": "923123"
}
}
Ad response
Organize and response advertising information in JSON format based on OPEN RTB 2.3 specification. Currently, only information for fix-price trade is included, RTB (Real Time Biding) will be added soon.
| Field | Description | Required | Type |
|---|---|---|---|
| id | bid Request ID | Y | string |
| bidid | bid response ID | Y | string |
| cur | ISO–4217 code bid currency | N | string |
| seatbid | seat Bid object | Y | object array |
| seat | bid qualification code | Y | string |
| bid | bid object array | Y | object array |
| id | bid object ID | Y | string |
| impid | impression object ID | Y | string |
| price | bid price | N | float |
| adm | ad markup(markup) | Y | string |
| iurl | image URL | Y | string |
| nurl | impression URL | Y | string |
| clickurl | click URL | Y | string |
Invoke tracking URL after applying Macro
If the value of the response’s nurl, clickurl, and add contains Macro below, respond instead.
| Macro | Processing |
|---|---|
| ${AUCTION_ID} | SSP replaces the macro to the BID Request ID so that the tracking URL is called. |
| ${AUCTION_PRICE} | SSP replaces the macro to WIN Price so that the tracking URL is called. Encoding with an integer greater than 0. (encoding method will be provided) |
Ad response example
{
"id": "req-12345-abcde",
"bidid": "mezzomedia",
"cur": "KRW",
"seatbid": [{
"seat": "512",
"bid": [{
"id": "147704390800",
"impid": "1",
"price": "40",
"adm": "<html><head><meta name='viewport' content='width=device-width; height=device-height;'><title></title></head><body style='margin:0px;'><style type='text/css'> #mz_first {position:absolute; left:0; top:0};</style><link href='http://abc.com/ad_images/r_main.css' rel='stylesheet' type='text/css' /><div id='mz_wrap' style='text-align:center;background-color:#000000; margin:0 auto; padding:0; text-decoration: none; width:100%;'><article id='mz_article' style='height:50px; margin:0 auto; overflow:hidden; position:relative; width:320px;'><a href='http://abc.com/ad_tracking.mezzo/?e_request_type=click&e_cp=${AUCTION_PRICE}&' target='_blank'><img id='mz_first' src='http://advimg.ad-mapps.com/ad_images/20160329_crewbi_2w_320x50.png' width='320' height='50'></a><div id='mz_beacon' style='position:absolute; left:0px; top:0px; visibility:hidden;'><img src='http://abc.com/ad_tracking.mezzo/?e_request_type=imps_tracking&e_cp=${AUCTION_PRICE}&'></div></article></div></body></html>",
"w": "320",
"h": "50",
"iurl": "http://abc.com/ad_images/20160329_abc_320x50.png",
"nurl": "http://abc.com/ad_tracking.mezzo/?e_request_type=imps_tracking&e_cp=${AUCTION_PRICE}&",
"ext": {
"clickurl": "http://abc.com/ad_tracking.mezzo/?e_request_type=click&e_cp=${AUCTION_PRICE}&"
}
}]
}]
}
Cookie matching
The Web performs ad audience matching through a separate process.
| 1 | SSP provides a URL for cookie matching to DSP. http://ssphost/match?dsp_user_id={dsp_uid} |
| 2 | DSP installs the url as a beacon form in advertiser or service page which can do a cookie matching in advance. (at least 2~3 weeks ago before integration) |
| 3 | When audience enters the installed page, browser calls the URL(SSP) by placing dsp_uid, SSP issues cookies with the passed dsp_uid value as ssphost. |
| 4 | SSP contains the issued dsp_uid value at the bid request to the DSP. |
Ad server error code definition
| Code | Description |
|---|---|
| 3 | invalid parameter (invalid bid request) |
| 4 | TARGETPICK setting error (invalid bid request) |
| 5 | No ad |
| 98 | incorrect tracking information |
| 99 | ad server error |
HTTP Response Status Code definition
| Status Code | Description | Body |
|---|---|---|
| 200 | normal bidding | refer to 2.3.2 |
| 204 | when giving up bidding | Empty body |
| 400 | invalid bid request | refer to 2.3.3 |
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==""
}
}
}]
}]
}