SSP Native AD. Request API
Geonjin Mun
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.5and OpenRTB Dynamic Native Ads API Specification Version 1.2 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 |
| native | object | Y | Refer to native 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). |
native
imp / native
| Field | Type | Required | Description |
|---|---|---|---|
| request | string | Y | Request payload complying with the Native Ad Specification. |
| ver | string | Y | Version of the Dynamic Native Ads API to which request complies. |
| battr | integer array | - | Blocked creative attributes. |
native_request
| Field | Type | Required | Description |
|---|---|---|---|
| ver | string | Y | |
| assets | object array | Y | Refer to native_asset object. |
| eventtrackers | object array | Y | Specifies what type of event tracking is supported. Refer to native_eventtracker object. |
| privacy | integer | - | Set to 1 when the native ad supports buyer-specific privacy notice. Set to 0(or field absent) when the native ad doesn’t support custom privacy links or if support is unknown. |
native_asset
imp / native / native_request
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | Y | A Unique asset ID, assigned by exchange. Typically a counter for the array. |
| required | integer | Y | Set to 1 of asset is required.(Exchange will not accept a bid without it.) |
| title | object | - | Refer to native_asset: Title object. |
| img | object | - | native_asset: Image object. |
| video | object | - | native_asset: Video object. |
| data | object | - | native_asset: Data object. |
native_asset: Title
imp / native / native_request / native_asset
| Field | Type | Required | Description |
|---|---|---|---|
| len | integer | Y | Maximum length of the text in the title element. |
native_asset: Image
imp / native / native_request / native_asset
| Field | Type | Required | Description |
|---|---|---|---|
| type | integer | Y | Type ID of the image element supported by the publisher. |
| w | integer | - | Width of the image in pixels. |
| h | integer | - | Height of the image in pixels. |
| wmin | integer | - | The minimum requested width of the image in pixels. |
| hmin | integer | - | The minimum requested height of the image in pixels. |
native_asset: Video
imp / native / native_request / native_asset
| Field | Type | Required | Description |
|---|---|---|---|
| mimes | string array | Y | Content MIME types supported. |
| minduration | integer | Y | Minimum video ad duration in seconds |
| maxduration | integer | Y | Maximum video ad duration in seconds. |
| protocols | integer array | Y | An array of video protocols the publisher can accept in the bid response. |
native_asset: Data
imp / native / native_request / native_asset
| Field | Type | Required | Description |
|---|---|---|---|
| type | integer | Y | Type ID of the element supported by publisher. |
| len | integer | - | Maximum length of the text in the element’s response. |
native_eventtracker
imp / native / native_request /
| Field | Type | Required | Description |
|---|---|---|---|
| event | integer | Y | Type of event available for tracking. |
| methods | integer array | Y | Array of the types of tracking available for the given event. |
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": "cdc-7c6d-4029-dcd|1337",
"test": 0,
"cur": "KRW",
"imp": [
{
"bidfloor":1.0,
"bidfloorcur":"USD",
"displaymanager":"SOMA",
"displaymanagerver":"sdkandroid_9-1-6",
"ext":{
},
"id":"1",
"instl":0,
"native":{
"battr":[
1,
3,
5,
8,
9
],
"request":"{
"ver":"1.2",\"plcmttype\":1,\"plcmtcnt\":1,\"seq\":0,\"aurlsupport\":0,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"wmin\":1200,\"hmin\":627}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"wmin\":50,\"hmin\":50}},{\"id\":5,\"required\":1,\"data\":{\"type\":2,\"len\":140}},{\"id\":6,\"required\":1,\"data\":{\"type\":12,\"len\":15}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1,2]}]}",
"ver":"1.2"
},
"secure":0,
"tagid":"130700475"
}
],
"app": {
"id": "test-pub-app-id",
"name": "test-pub-app-name",
"bundle": "com.mezzo.co.kr ",
"storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
"cat": "IAB1",
"publisher": {
"id": "test-pub-app-id",
"domain": "test-pub-domain",
"product_attr": 1
}
},
"device": {
"adid": "test-ifa-gaid",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
"dnt": 0,
"ip": "192.168.1.1",
"make":"iOS",
"model": "iPhone 7,2",
"os": "iOS",
"osv": "8.0",
"js": 1,
"ifa": "test-ifa-gaid"
},
"user": {
"id": "923123"
},
"ext": {
"price_type": 1,
"click_macro": 1
}
}
RESPONSE
DSP SSP
DSP responds by including the objects defined below in HTTP body.
Object definitions follow the OPEN RTB 2.5 and OpenRTB Dynamic Native Ads API Specification Version 1.2 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 | Y | Refer to native_response 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 | string | Y | extension area |
native_response
bid / adm /
| Field | Type | Required | Description |
|---|---|---|---|
| ver | string | Y | Version of the Native Markup version in use. |
| assets | object array | Y | List of native ad’s assets. Refer to native_response_asset object. |
| link | object | Y | Refert to native_response_asset_link object. |
| eventtrackers | object array | Y | Refer to native_response_asset_eventtracker object. |
| privacy | string | Y | If support was indicated in the request, URL of a page informing the user about the buyer’s targeting activity. |
native_response_asset
bid / adm / native_response
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | Y | Unique asset ID, assigned by exchange. Typically a counter for the array. Code to match the request asset object. |
| required | integer | Y | Set to 1 if asset is required. |
| title | object | - | Refer to native_response_asset_title object. |
| img | object | - | Refer to native_response_asset_image object. |
| video | object | - | Refer to native_response_asset_video object. |
| data | object | - | Refer to native_response_asset_data object. |
native_response_asset: Title
bid / adm / native_response / native_response_asset
| Field | Type | Required | Description |
|---|---|---|---|
| text | string | Y | The text associated with the text element. |
native_response_asset: Image
bid / adm / native_response / native_response_asset
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | Y | URL of the image asset. |
| w | integer | Y | Width of the image in pixels. |
| h | integer | Y | Height of the image in pixels. |
native_response_asset: Video
bid / adm / native_response / native_response_asset
| Field | Type | Required | Description |
|---|---|---|---|
| vasttag | string | Y | vast xml |
native_response_asset: Data
bid / adm / native_response / native_response_asset
| Field | Type | Required | Description |
|---|---|---|---|
| value | string | Y | The formatted string of data to be displayed. |
native_response_asset: Link
bid / adm / native_response / native_response_asset
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | Y | List of third-party tracker URLs to be fired on click of the URL. |
native_response_eventtracker
bid / adm / native_response /
| Field | Type | Required | Description |
|---|---|---|---|
| event | integer | Y | Type of event to track. |
| methods | integer | Y | Type of tracking requested. |
Bid response example
{
"id": "ece5c105-dd24-468f-8392-d624b8d49953",
"seatbid": [
{
"bid": [
{
"id":"5d7801c2be564c8100f00011-1062015",
"price":2.0,
"impid":"1",
"nurl":"http://node-p2e-gie4ah.sitescout.com/smaato/win/aid:5d7801c2be564c8100f00011;c:${AUCTION_PRICE};s:;cid:1062015;ts:1568145858061;d:MzMzMTUwMi1uYXRpdmU",
"adm":"{\"native\":{\"link\":{\"url\":\"http://clickserv.sitescout.com/clk/8cc00d7733a331ba/88e42568017fb609/0-0/0///~_aid_~5d7801c2be564c8100f00011//cidentLy8vLy8\",\"clicktrackers\":[\"https://adrta.com/c?clid=ss&paid=ss&cb=1568145858061&avid=112053&caid=1062015&publisherId=1100043642&kv5=&plid=3331502&segment=&kv4=100.10.38.5&kv14=&kv1=native&siteId=120207704&kv7=17&kv15=UNKNOWN&kv16=&kv17=&kv18=com.particlenews.newsbreak&kv24=MOBILE_APP&kv20=&kv21=eb6fe99843ff5310bd0cd40d267826fff05d8aa3&kv22=9863a35c-c598-4c80-b091-d7adf379bb26&kv11=5d7801c2be564c8100f00011&kv3=&kv2=\"]},\"ver\":\"1.2\",\"assets\":[{\"id\":5,\"required\":1,\"data\":{\"type\":2,\"value\":\"Lose 3 to 5 pounds per week. Keep it off with free support for life!\"}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"url\":\"http://cdn01.basis.net/112100/112053/uhSvl5gEElOXwX0T.jpg\",\"w\":1200,\"h\":627}},{\"id\":1,\"required\":1,\"title\":{\"text\":\"Lose Weight For Life!\"}},{\"id\":6,\"required\":1,\"data\":{\"type\":12,\"value\":\"Learn more\"}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"url\":\"http://cdn01.basis.net/112100/112053/5MkC88n4Mc8MdPa4.jpg\",\"w\":240,\"h\":240}}],\"imptrackers\":[\"https://node-p2e-gie4ah.sitescout.com/smaato/px/aid:5d7801c2be564c8100f00011;c:${AUCTION_PRICE};s:;cid:1062015;ts:1568145858061\",\"https://pixel-sync.sitescout.com/dmp/pixelSync?nid=17&wb=1&hdid=0&id=9863a35c-c598-4c80-b091-d7adf379bb26&idType=4\",\"https://ad.doubleclick.net/ddm/trackimp/N428001.3027484BASISDSP/B22322261.248240382;dc_trk_aid=447774364;dc_trk_cid=119057854;u=210363%7C5d7801c2be564c8100f00011%7C%7Ccom.particlenews.newsbreak%7CAWAKEN002CP+%5BCPA%5D+GT+%28Zips%2B15+mi%29_Display%7CMOBILE_APP%7C1062015;ord=[timestamp];dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?\"],\"jstracker\":\"\"}}",
"adomain":[
"awaken180weightloss.com"
],
"iurl":"http://preview.sitescout.ad/preview?adOnly=1&ad=8cc00d7733a331ba",
"crid":"3331502",
"cid":"1062015",
"attr":[
],
"cat":[
"IAB7-44",
"IAB7"
]
}
],
"seat":"18878"
}
],
"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==""
}
}
}]
}]
}