Banner

Guide for SSP Banner Inventory Integration with CJ MezzoMedia DSP

1. REQUEST

Construct the content below in JSON format according to the OpenRTB 2.5 specification, then call the above URL using the POST method.

Currently, only the information for fixed-price transactions is defined in the OpenRTB 2.5 specification. Information for RTB (Real-Time Bidding) will be added in a future update.

Request object

Field	Type	Required	Description
ssp_id	string	Y	SSP ID (issued by TARGETPICK)
id	string	Y	Unique request ID
cur	string array	N	Currency for auction (ISO-4217-alpha), e.g., “KRW”
imp	object array	Y	Refer to the imp object
site	object	Y	Refer to the site object
app	object	Y	Refer to the app object
publisher	object	Y	Refer to the publisher object
device	object	Y	Refer to the device object
user	object	Y	Refer to the user object
at	integer	Y	0: fixed price 1: first price 2: second price
tmax	integer	Y	Maximum timeout (ms)
bcat	string array	N	Block advertiser categories based on IAB categories
badv	string array	N	Block advertiser domains
bapp	string array	N	Block app bundle or package names

Imp

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

Banner

imp / banner

Field	Type	Required	Description
w	integer	Y	Banner width
h	integer	Y	Banner height

Site

Field	Type	Required	Description
id	string	Y	Unique site ID managed by SSP
name	string	N	Site name
domain	string	Y	Site domain
page	string	N	Page URL
ref	string	N	Referrer URL
cat	string array	N	Categories

App

Field	Type	Required	Description
id	string	Y	Unique app ID managed by SSP
name	string	N	Application name
bundle	string	Y	Bundle or package name
storeurl	string	N	App store URL
cat	string array	N	Categories

Publisher

Field	Type	Required	Description
id	string	Y	Publisher ID

Device

Field	Type	Required	Description
ua	string	Y	User Agent
ip	string	Y	IPv4 address
model	string	N	Device model
os	string	Y	iOS , Android, mobile_web, pc_web
osv	string	Y	OS version (e.g., 8.1, 9.2)
ifa	string	Y	Apple IFA or Google ADID
geo	object	N	Country code (ISO 3166-1 Alpha-3)

• User Agent (UA) is required for ad exchange transactions.

• IP must be a public IP. Using private IP (e.g., from internal networks or routers) may limit ad delivery.

User

Field	Type	Required	Description
buyeruid	string	Y	Cookie matching ID received from Mezzo

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

WEB

2. RESPONSE

Respond by composing the ad information in JSON format according to the OpenRTB 2.5 specification.

Currently, only information for fixed-price transactions is included, and RTB (Real-Time Bidding) details will be added later.

Filed	Type	Required	Description
id	string	Y	Bid Request ID
bidid	string	Y	Bid response ID
cur	string	N	Bid currency in ISO-4217 code
seatbid	object array	Y	Seat Bid object
seat	string	Y	Bidder qualification code (not used)
bid	object array	Y	Array of Bid objects
id	string	Y	Bid object ID
impid	string	Y	Impression object ID
price	float	N	Bid price
adm	string	Y	Ad markup
iurl	string	Y	Image URL
nurl	string	Y	Impression URL
clickurl	string	Y	Click URL

Macro Applied on Tracking URL Call

In the response, if the values of the nurl, clickurl, or adm fields contain the macros below, replace them before responding.

Macro	Description
${AUCTION_ID}	Replaced with the Bid Request ID so the tracking URL is called from the SSP
${AUCTION_PRICE}	Replaced with the WIN price on the SSP side. Converted to an encrypted integer value of 0 or greater. (The encryption method will be provided later.)
${SSP_CLICK_URL}	URI-encoded and replaced with a URL that allows the SSP to verify the click event by calling the SSP URL when a click event occurs
${SSP_CLICK_URL:2}	URI-encoded twice and replaced macro. When a click event occurs, the SSP URL is called so the click event can be verified

Example

Response

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

3. Cookie Matching

The web performs ad audience matching through a separate process.

1	SSP provides a URL for cookie matching to the DSP: http://ssphost/match?dsp_user_id={dsp_uid}
2	DSP installs the above URL in advance as a beacon on advertiser or service pages where cookie matching is possible. (At least 2–3 weeks before integration.)
3	When an audience visits the installed page, the browser requests the SSP URL with dsp_uid, and the SSP issues a cookie for the received dsp_uid value to ssphost.
4	Going forward, the SSP includes the issued dsp_uid value in Bid Requests sent to the DSP.

Ad Server Error Codes

Code	Description
3	Invalid parameter information delivered (invalid bid request)
4	No TARGETPICK inventory (invalid bid request)
5	No ad creative to serve
98	Invalid tracking information
99	Ad server error

HTTP Response Status Codes

Status Code	Description	Body
200	Successful bid	Refer to 2.3.2
204	No bid / give up bidding	Empty body
400	Invalid bid request	Refer to 2.3.3

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