Native

OpenRTB specifications for native ad integration.

1. REQUEST

SSP ➡️ DSP

CJ MezzoMedia SSP sends a request to the DSP interface via HTTP POST with the object defined below in JSON format. The request object follows the OpenRTB 2.5 and OpenRTB Dynamic Native Ads API Specification Version 1.2.

Request object

Field	Type	Required	Description
id	string	Y	Unique request ID
cur	string array	N	ISO-4217 alpha currencies allowed in the auction (e.g., "KRW")
test	integer	N	Indicates whether the auction is in test mode (1) or live mode (0). Bidding is not allowed for test auctions
site	object	Y	Refer to the Site object
app	object	Y	Refer to the App object
device	object	Y	Refer to the Device object
user	object	Y	Refer to the User object
imp	object array	Y	Array of Imp objects
at	integer	Y	0: fixed price 1: first price 2: second price
tmax	integer	Y	Maximum timeout in milliseconds (ms)
bcat	string array	N	Blocked advertiser categories based on IAB categories
badv	string array	N	Blocked advertiser domains
bapp	string array	N	Blocked app bundle or package names
ext	object	N	Refer to the 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	Referrer URL (previous page URL)
cat	string array	N	Categories
publisher	object	Y	Refer to the Publisher object

App

Field	Type	Required	Description
id	string	Y	Publisher ID
name	string	N	Application name
bundle	string	Y	Bundle name or package name
storeurl	string	N	App store URL
cat	string array	N	Categories
publisher	object	Y	Refer to the 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: banner 2: interstitial

Device

Field	Type	Required	Description
adid	string	Y	Device advertising ID
make	string	Y	Device make (e.g., “samsung”)
ua	string	Y	User Agent of the device
dnt	integer	N	Do Not Track flag 0: tracking allowed 1: tracking restricted
ip	string	Y	IPv4 address
model	string	N	Device model
os	string	Y	Operating system (e.g., iOS, Android)
osv	string	Y	OS version (e.g., 8.1, 9.2)
js	integer	N	Defined as 1 in RTB protocol
ifa	string	Y	Apple IFA or Google ADID

User

CJ MezzoMedia Extension Field

Field	Type	Required	Description
id	string	Y	Unique user ID

Imp

Field	Type	Required	Description
id	string	Y	Unique impression ID
bidfloor	float	Y	Minimum bid price required to be considered valid (e.g., 4.12)
bidfloorcur	string	Y	Currency (e.g., "KRW")
secure	integer	Y	0 : http 1 : https
type	string	Y	Native
native	object	Y	Refer to th Native object
instl	integer	Y	Indicates whether the ad is interstitial (default: 0) 1: the ad is interstitial or full screen 0: not interstitial
displaymanager	string	Y	SSP platform name or SDK name
displaymanagerver	string	Y	SSP platform or SDK version

Native

Imp / native

Field	Type	Required	Description
request	string	Y	Valid request for native ads
ver	string	Y	Version of the Dynamic Native Ads API in use
battr	integer array	-	Blocked creative attributes

Native_request

Imp / Native

Field	Type	Required	Description
ver	string	Y	Native markup version in use
assets	object array	Y	Array of Native_asset objects
privacy	integer	-	0: not supported 1: supports buyer privacy policy

Native_asset

Imp / Native / Native_request

Field	Type	Required	Description
id	integer	Y	Unique Asset ID
required	integer	Y	Set to 1 if the asset is required
title	object	-	Refer to the Native_asset: Title object
img	object	-	Refer to the Native_asset: Image object
video	object	-	Refer to the Native_asset: Video object
data	object	-	Refer to the Native_asset: Data object

Native_asset: Title

Imp / Native / Native_request / Native_asset

Field	Type	Required	Description
len	integer	Y	Maximum length of the title text

Native_asset: Image

Imp / Native / Native_request / Native_asset

Field	Type	Required	Description
type	integer	Y	Type ID of the image asset supported by the publisher
w	integer	-	Image width in pixels
h	integer	-	Image height in pixels
wmin	integer	-	Minimum requested image width
hmin	integer	-	Minimum requested image height

Native_asset: Video

Imp / Native / Native_request / Native_asset

Field	Type	Required	Description
mimes	string array	Y	Supported MIME types
minduration	integer	Y	Minimum video ad duration (seconds)
maxduration	integer	Y	Maximum video ad duration (seconds)
protocols	integer array	Y	Supported video protocol types by the publisher

Native_asset: Data

Imp / Native / Native_request / Native_asset

Field	Type	Required	Description
type	integer	Y	Data asset type ID supported by the publisher
len	integer	-	Maximum length of the data response

Ext

CJ MezzoMedia Extension Field

Field	Type	Required	Description
price_type	integer	N	0: CPM 1: CPC
click_macro	integer	N	1: DSP must provide macro (${MEZZO_CLICK_URL}) within ADM for click tracking. When a click occurs, the macro-substituted click URL must be triggered

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}}]}",
            "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://play.google.com/store/apps/details?id=com.mezzo.co.kr",
      "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":"samsung",
      "model": "SM-G955N",
      "os": "Android",
      "osv": "9",
      "js": 1,
      "ifa": "test-ifa-gaid"
   },
   "user": {
      "id": "923123"
   },
   "ext": {
      "price_type": 1,
      "click_macro": 1
   }
}

2. RESPONSE

DSP ➡️ SSP

The DSP responds by including the object defined below in the HTTP body. The object definition follows the OpenRTB 2.5 and OpenRTB Dynamic Native Ads API Specification Version 1.2.

Bid Response

Response object in JSON format.

Field	Type	Required	Description
id	string	Y	ID of the Bid Request
bidid	string	Y	ID of the Bid object
cur	string	Y	Currency used for bidding (e.g., KRW)
seatbid	object array	Y	Array of Seatbid objects. At least one is required for a valid bid

Seatbid

Field	Type	Required	Description
seat	string	Y	ID managing the bidding entity
bid	object array	Y	Array of Bid objects. At least one is required for a valid bid

Bid

Field	Type	Required	Description
id	string	Y	ID managing the bid
impid	string	Y	Impression ID related to the bid request. Must match the impression object ID in the request
price	float	Y	Bid price
cat	string array	Y	Categories
nurl	string	N	Win notice URL. The clearing price is substituted into the {AUCTION_PRICE} macro
burl	string	N	Billing notice URL. The clearing price is substituted into the {AUCTION_PRICE} macro
lurl	string	N	Loss notice URL. The loss reason code is substituted into the {AUCTION_LOSS} macro
adm	string	Y	Refer to the Native_response object
iurl	string	Y	Impression image URL
adomain	string array	Y	Advertiser domains for blacklist checking
cid	string	Y	Advertiser campaign name / ID
crid	string	Y	Creative name / ID
w	integer	Y	Ad width
h	integer	Y	Ad height
ext	string	Y	Extension field

Native_response

Bid / adm

Field	Type	Required	Description
ver	string	Y	Native markup version
assets	object array	Y	Native ad assets Array of Native_response_asset objects
link	object	Y	Refer to the Native_response_asset: Link object
eventtrackers	object array	Y	Array of Native_response_asset: Eventtracker objects
privacy	string	Y	Response value for privacy requests. If not provided, MezzoMedia logo will be displayed

Native_response_asset

Bid / adm / Native_response

Field	Type	Required	Description
id	integer	Y	Unique asset ID
required	integer	-	Set to 1 if the asset is required
title	object	-	Refer to the Native_response_asset: Title object
img	object	-	Refer to the Native_response_asset: Image object
video	object	-	Refer to the Native_response_asset: Video object
data	object	-	Refer to the Native_response_asset: Data object

Native_response_asset: Title

Bid / adm / Native_response / Native_response_asset

Field	Type	Required	Description
text	string	Y	Text associated with the title asset

Native_response_asset: Image

Bid / adm / Native_response / Native_response_asset

Field	Type	Required	Description
url	string	Y	Image asset URL
w	integer	Y	Image width in pixels
h	integer	Y	Image height 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	Formatted string to be displayed for the data asset

Native_response_asset: Link

Bid / adm / Native_response / Native_response_asset

Field	Type	Required	Description
url	string	Y	Clickable landing URL

Native_response_asset: Eventtracker

Bid / adm / Native_response / Native_response_asset

Field	Type	Required	Description
event	integer	Y	Type of event to track
methods	integer	Y	Requested tracking method

Example

success

{
  "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}}],\"eventtrackers\":[\"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"
}

noad

{
  "id": "",
  "seatbid": [],
  "bidid": "mezzo",
  "cur": "KRW"
}

3. SKAdNetwork Support (iOS 14+)

This section describes support for campaigns where SKAdNetwork is enabled on iOS 14 or later.

1	The DSP must be registered as an Ad Network in Apple’s SKAdNetwork API. (https://developer.apple.com/documentation/storekit/skadnetwork/registering_an_ad_network)
2	A public key must be issued by Apple and a postback URL must be configured.
3	The SKAdNetwork ID issued by Apple must be shared with CJ MezzoMedia, which will request registration in the publisher’s info.plist.
4	When returning a response for SKAdNetwork-enabled campaigns, the DSP must include the SKAdNetwork ID and all related fields.
5	The advertiser app must register via registerAppForAdNetworkAttribution().
6	The DSP can receive install data via SKAdNetwork.

Additional Fields in Ad Request (SKAdNetwork)

BidRequest / imp / banner / ext / skadn

Prerequisites:

1	The DSP’s SKAdNetwork ID must be registered in the publisher’s info.plist.
2	The user device must run iOS 14 or higher.
3	A version of the SDK that supports SKAdNetwork must be installed.
4	The DSP must comply with CJ MezzoMedia Bid Request specifications.

Field	Type	Required	Description	Example
version	string	Y	SKAdNetwork version (2.0 or higher)	“version”:”2.0”
sourceapp	string	Y	Publisher app ID registered in Apple App Store. Matches BidRequest.app.bundle	“sourceapp”:”000000000”
skadnetids	string	Y	SKAdNetwork IDs registered in publisher’s info.plist	“skadnetids”:[“feyaarzu9v.skadnetwork”]

Additional Fields in Ad Response (SKAdNetwork)

BidResponse / imp / banner / ext / skadn

Field	Type	Required	Description	Example
version	string	Y	SKAdNetwork version (2.0 or higher)	“version”:”2.0”
network	string	Y	Ad network identifier. Must match at least one skadnetid in the request	“network”:[“feyaarzu9v.skadnetwork”]
campaign	string	Y	Campaign ID (integer between 1 and 100 per Apple spec)	“campaign”:”45”
itunesitem	string	Y	Advertiser app ID in App Store. Matches BidResponse.bid.bundle	“itunesitem”:”123456789”
nonce	string	Y	Unique ID for each ad response	“nonce”:”123b1a78-b5ef-98ad-1234-ab-c4effa00b8”
sourceapp	string	Y	Publisher app ID. Matches BidRequest.imp.ext.skad.sourceapp	“sourceapp”:”000000000”
timestamp	string	Y	Unix time as a string	“timestamp”:”1234567890”
signature	string	Y	SKAdNetwork signature provided by Apple	“signature”:”ABCDEFGHijkl-lmb…”

Example

Request

{
	"imp":[{
        "ext": {
          "skadn": {
            "version": "2.0",
			"sourceapp": "000000000",
			"skadnetids": ["feyaarzu9v.skadnetwork", "8sRFag4vVC.skadnetwork"]
			}
			}
		}]
}

Response

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