DSP Native AD. Delivery API

14 minute read

InJun Kim

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 and 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.

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": {
   }
}

RESPONSE

DSP SSP

DSP responds by including the objects defined below in HTTP body.

Object definitions follow the OPEN RTB 2.3 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	Y	impression URL
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	string	Y	creative width size
h	string	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&amp;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==""
				}
			}
		}]
	}]
}