SSP Native AD. Request API

15 minute read

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

imp / native /

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.

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==""
				}
			}
		}]
	}]
}

Updated: