배너 광고

CJ 메조미디어 DSP에 SSP 배너 인벤토리 연동 시 가이드 입니다.

1. API 목록

서비스	광고 상품	응답 포맷
TARGETPICK	띠배너 전면배너 정사각형 및 직사각형 스카이스크래퍼 리더보드	JSON

2. 도메인 정보

구분	URL
테스트	보안 정책의 이슈로 테스트 진행 시 제공합니다.
상용	보안 정책의 이슈로 테스트 완료 후 제공합니다.

3. 광고 요청

{domain}/dsp.mezzo/?ssp_id={ssp_id}

아래 내용을 OPEN RTB 2.5 규격의 JSON 형태로 구성한 뒤, 위의 URL 을 POST 방식으로 호출합니다.

현재는 OPEN RTB 2.5 규격에서 고정가 거래를 위한 내용만 정의되어 있습니다. 추후 RTB (Real Time Biding) 에 대한 내용이 업데이트 될 예정입니다.

Request object

필드	유형	필수	설명
ssp_id	string	Y	SSP ID (TARGETPICK 에서 발급)
id	string	Y	요청 유니크 아이디
cur	string array	N	ISO-4217-alpha 경매에 사용할 수 있는 통화 입니다. 예: “KRW”
imp	object array	Y	imp 객체를 참고하십시오.
site	object	Y	site 객체를 참고하십시오.
app	object	Y	app 객체를 참고하십시오.
publisher	object	Y	publisher 객체를 참고하십시오.
device	object	Y	device 객체를 참고하십시오.
user	object	Y	user 객체를 참고하십시오.
at	integer	Y	0 : fixed price, 1: first price, 2: second price
tmax	integer	Y	최대허용시간 (ms).
bcat	string array	N	IAB 카테고리 기준으로 광고주 카테고리를 차단합니다.
badv	string array	N	광고주의 도메인을 차단합니다.
bapp	string array	N	App의 번들이나 패키지명을 차단합니다.

Imp

필드	유형	필수	설명
id	string	Y	노출에 대한 유니크 아이디
bidfloor	float	Y	입찰로 인정받을 수 있는 최소 가격. 예) 4.12
bidfloorcur	string	Y	통화, 예) ‘KRW’
secure	integer	Y	0 : http, 1 : https
banner	object	Y	banner 객체를 참고하십시오.
instl	integer	Y	전면광고 여부를 전달합니다. (default : 0) * 1 = the ad is interstitial or full screen * 0 = not interstitial
displaymanager	string	Y	SSP 플랫폼명 또는 SDK명을 의미합니다.
displaymanagerver	string	Y	SSP 플랫폼 또는 SDK 버전을 의미합니다.

Banner

imp / banner

필드	유형	필수	설명
w	integer	Y	배너의 가로 크기
h	integer	Y	배너의 세로 크기

Site

필드	유형	필수	설명
id	string	Y	SSP에서 관리하는 사이트 고유 ID
name	string	N	사이트 이름
domain	string	Y	사이트 도메인
page	string	N	페이지 url
ref	string	N	현재페이지로 이동해오기 바로 전 페이지의 주소
cat	string array	N	카테고리

App

필드	유형	필수	설명
id	string	Y	SSP에서 관리하는 APP 고유 ID
name	string	N	애플리케이션 이름
bundle	string	Y	번들 이름, 패키지 이름
storeurl	string	N	앱스토어 URL
cat	string array	N	카테고리

Publisher

필드	유형	필수	설명
id	string	Y	퍼블리셔 ID

Device

필드	유형	필수	설명
ua	string	Y	디바이스의 User Agent 정보
ip	string	Y	IPV4 주소
model	string	N	모델명
os	string	Y	iOS , Android, mobile_web, pc_web
osv	string	Y	운영체제 버전. 예) 8.1, 9.2
ifa	string	Y	Apple IFA 또는 Google 의 ADID
geo	object	N	ISO 3166-1 Alpha-3은 ISO 3166-1에서 정한 코드값 country

• UA(User Agent)의 경우, AD Exchange 거래를 위한 조건으로 반드시 필수 제공해주셔야 합니다.

• IP의 경우, Private IP(가상IP)가 아닌 Public IP 기준으로 전달주셔야 합니다. 공유기, 회사 내부망에 할당된 IP가 그대로 전달 될 경우 광고 거래가 제한적일 수 있습니다.

User

필드	유형	필수	설명
buyeruid	string	Y	메조한테 전달받은 쿠키매칭 id

광고 요청 예제 (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)

{
	"id": "req-12345-abcde",
	"imp": [{
		"id": "1",
		"bidfloor": 0,
		"secure": 0,
		"bidfloorcur": "KRW",
		"instl": 0,
		"banner": {
			"w": 320,
			"h": 50,
			"btype": [1, 3, 4]
		}
	}],
	"site": {
		"id": "g0r8k3u5",
		"name": "test",
		"domain": "gamefocus.co.kr",
		"page": "http://gamefocus.co.kr",
		"ref": "http://www.naver.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"
   }
}

4. 광고 응답

OPEN RTB 2.3 규격의 JSON 형태로 광고 정보를 구성해 응답합니다.

현재는 고정가 거래를 위한 정보만 포함하며, 추후 RTB (Real Time Biding) 에 대한 내용도 포함될 예정입니다.

Filed Name	Filed Value(설명)	필수	타입	예시/설명
id	Bid Request 의 ID	Y	string	Bid Request 의 ID
bidid	비딩 응답의 ID	Y	string	비딩 응답의 ID
cur	ISO–4217 코드의 입찰 통화	N	string	ISO–4217 코드의 입찰 통화
seatbid	Seat Bid 오브젝트	Y	object array	Seat Bid 오브젝트
seat	입찰자격코드	Y	string	입찰자격코드(사용안함)
bid	Bid 오브젝트의 배열	Y	object array	Bid 오브젝트의 배열
id	Bid 오브젝트의 ID	Y	string	Bid 오브젝트의 ID
impid	Impression 오브젝트의 ID	Y	string	Impression 오브젝트의 ID
price	입찰 가격	N	float	입찰 가격
adm	광고 마크업(markup)	Y	string	광고 마크업(markup)
iurl	이미지URL	Y	string	이미지URL
nurl	노출 URL	Y	string	노출 URL
clickurl	클릭 URL	Y	string	클릭 URL

Macro 적용 후 트래킹 URL 호출

Response 에 nurl, clickurl, adm 속성값에 아래를 Macro 가 포함된 경우 이를 대체하여 응답합니다.

Macro	처리 내용
${AUCTION_ID}	SSP에서는 BID Request ID 로 치환하여 트래킹 URL이 호출되도록 합니다.
${AUCTION_PRICE}	SSP에서는 WIN Price 낙찰 단가로 치환하여 트래킹 URL이 호출되도록 합니다. 0 이상의 정수로 암호화 합니다. (암호화 방식은 추후 제공)
${SSP_CLICK_URL}	SSP에서 클릭이벤트를 확인 할 수있는 URL URI인코딩 후 치환하여 클릭이벤트 발생시 SSP URL을 호출하여 클릭이벤트 발생여부 확인 할 수 있습니다.
${SSP_CLICK_URL:2}	SSP에서 클릭이벤트를 2번 URI인코딩 후 치환 Macro이며 클릭이벤트 발생시 SSP URL을 호출하여 클릭이벤트 발생여부 확인 할 수 있습니다.

광고 응답 예제

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

쿠키매칭

웹은 별도의 프로세스를 통해서 광고 오디언스 매칭을 수행합니다.

1	SSP에서는 DSP에게 쿠키매칭을 위한 URL을 제공한다. http://ssphost/match?dsp_user_id={dsp_uid}
2	DSP에서는 사전에 쿠키매칭이 가능한 광고주 또는 서비스페이지에 미리 해당URL을 비콘 형태로 설치한다. (최소 연동 2~3주 전)
3	설치된 페이지에 유입되는 오디언스의 브라우저에서는 해당 URL(SSP)로 dsp_uid를 담아 요청하게 되고, SSP에서는 전달된 dsp_uid 값을 ssphost로 쿠키를 발급한다.
4	향후 SSP는 DSP에 Bid Request 시 발급된 dsp_uid 값을 포함하여 요청한다.

광고 서버 에러 코드 정의

코드	설명
3	잘못된 파라미터 정보 전달 (잘못된 입찰 요청)
4	TARGETPICK 지면 없음 (잘못된 입찰 요청)
5	송출 광고물 없음
98	잘못된 트래킹 정보
99	광고 서버 에러

HTTP Response Status Code 정의

Status Code	설명	Body
200	정상적인 입찰의 경우	2.3.2 참조
204	입찰을 포기할 경우	Empty body
400	잘못된 입찰 요청	2.3.3 참조

SKAdNetwork 지원(iOS14 이상)

해당 내용은 iOS14 버전 혹은 그 이상의 환경에서 SKAdNetwork가 활성화된 캠페인을 지원하기 위한 내용입니다.

1	DSP는 Apple의 SKAdNetwork API에 Ad Network로 등록되어 있어야 한다. (https://developer.apple.com/documentation/storekit/skadnetwork/registering_an_ad_network)
2	Apple로부터 Public key를 발급받고 Postback URL을 설정해야 한다.
3	Apple로부터 발급받은 SKAdNetwork ID를 MezzoMedia 담당자에게 전달하고 MezzoMedia는 전달받은 SKAdNetwork ID를 자사와 제휴된 퍼블리셔의 info.plist에 등록 요청한다.
4	DSP에서 SKAdNetwork가 활성화된 캠페인 Response를 전달할 때는 SKAdNetwork ID 및 관련된 모든 정보를 포함해야한다.
5	광고주 App은 registerAppForAdNetworkAttribution()를 통해 SKAdNetwork 사용자로 등록해야 한다.
6	DSP는 SKAdNetwork를 통해 설치 데이터를 제공 받을 수 있다.

광고요청 추가내용 (SKAdNetwork)

BidRequest / imp / banner / ext / skadn

해당 Object를 사용하기 위해서는 우선적으로 아래 사항들이 준비되어야 합니다.

1	DSP에서 제공하는 SKAdNetwork ID가 퍼블리셔의 info.plist에 등록되어 있어야 한다.
2	사용자 기기의 운영체제가 iOS14 혹은 그 이상이어야 한다.
3	SKAdNetwork를 지원하는 버전의 SDK를 설치해야한다.
4	DSP는 메조미디어의 Bid Request 규약을 준수해야한다.

필드	유형	필수	설명	예
version	string	Y	사용하는 SKadNetwork 버전. “2.0” 혹은 그 이상.	“version”:”2.0”
sourceapp	string	Y	Apple App 스토어에 등록된 퍼블리셔 App ID. ‘BidRequest.app.bundle’ 과 매칭	“sourceapp”:”000000000”
skadnetids	string	Y	퍼블리셔 App 내 info.plist에 입력된 SKAdNetwork IDs	“skadnetids”:[“feyaarzu9v.skadnetwork”]

SKAdNetwork 광고 요청 예제

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

광고응답 추가내용 (SKAdNetwork)

BidResponse / imp / banner / ext / skadn

필드	유형	필수	설명	예
version	string	Y	사용하는 SKadNetwork 버전. “2.0” 혹은 그 이상.	“version”:”2.0”
network	string	Y	광고 네트워크 식별자. Request에 포함된 skadnetids와 최소 한 개는 매칭되어야 함	“network”:[“feyaarzu9v.skadnetwork”]
campaign	string	Y	Apple의 규격에 맞는 캠페인 ID. 1과 100 사이의 정수를 이용해서 표현해야함	“campaign”:”45”
itunesitem	string	Y	Apple App 스토어에 등록된 광고주 App ID. ‘Bidresponse.bid.bundle’과 매칭	“itunesitem”:”123456789”
nonce	string	Y	개별 광고 response의 유니크 ID	“nonce”:”123b1a78-b5ef-98ad-1234-ab-c4effa00b8”
sourceapp	string	Y	Apple App 스토어에 등록된 퍼블리셔 App ID. ‘BidRequest.imp.ext.skad.sourceapp’ 과 매칭	“sourceapp”:”000000000”
timestamp	string	Y	Unix time을 string 값으로 전달	“timestamp”:”1234567890”
signature	string	Y	Apple에서 제공하는 SKAdNetwork sigature 값	“signature”:”ABCDEFGHijkl-lmb…”

SKAdNetwork 광고 응답 예제

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