# 배너 광고

## 1. **API 목록**

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

## **2. 도메인 정보**

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

## **3. 광고 요청**

{% hint style="info" %}
{domain}/dsp.mezzo/?ssp\_id={ssp\_id}
{% endhint %}

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

현재는 [OPEN RTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) 규격에서 고정가 거래를 위한 내용만 정의되어 있습니다.\
추후 RTB (Real Time Biding) 에 대한 내용이 업데이트 될 예정입니다.

### **Request object**

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

### **Imp**

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

### **Banner**

> [imp](https://docs.meba.kr/s-plus/api/dsp/delivery/banner/#banner_imp) / banner

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

### **Site**

<table><thead><tr><th width="136">필드</th><th width="139">유형</th><th width="64">필수</th><th>설명</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Y</td><td>SSP에서 관리하는 사이트 고유 ID</td></tr><tr><td>name</td><td>string</td><td>N</td><td>사이트 이름</td></tr><tr><td>domain</td><td>string</td><td>Y</td><td>사이트 도메인</td></tr><tr><td>page</td><td>string</td><td>N</td><td>페이지 url</td></tr><tr><td>ref</td><td>string</td><td>N</td><td>현재페이지로 이동해오기 바로 전 페이지의 주소</td></tr><tr><td>cat</td><td>string array</td><td>N</td><td>카테고리</td></tr></tbody></table>

### **App**

<table><thead><tr><th>필드</th><th>유형</th><th width="100">필수</th><th>설명</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Y</td><td>SSP에서 관리하는 APP 고유 ID</td></tr><tr><td>name</td><td>string</td><td>N</td><td>애플리케이션 이름</td></tr><tr><td>bundle</td><td>string</td><td>Y</td><td>번들 이름, 패키지 이름</td></tr><tr><td>storeurl</td><td>string</td><td>N</td><td>앱스토어 URL</td></tr><tr><td>cat</td><td>string array</td><td>N</td><td>카테고리</td></tr></tbody></table>

### **Publisher**

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

### **Device**

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

{% hint style="danger" %}

* UA(User Agent)의 경우, AD Exchange 거래를 위한 조건으로 <mark style="color:red;">**반드시 필수 제공**</mark>해주셔야 합니다.
* IP의 경우, <mark style="color:red;">**Private IP(가상IP)가 아닌 Public IP 기준으로 전달**</mark>주셔야 합니다.\
  공유기, 회사 내부망에 할당된 IP가 그대로 전달 될 경우 광고 거래가 제한적일 수 있습니다.
  {% endhint %}

### **User**

<table><thead><tr><th>필드</th><th width="116">유형</th><th width="104">필수</th><th>설명</th></tr></thead><tbody><tr><td>buyeruid</td><td>string</td><td>Y</td><td>메조한테 전달받은 쿠키매칭 id</td></tr></tbody></table>

#### **광고 요청 예제 (app)**

{% code lineNumbers="true" %}

```json
{
	"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"
   }
}
```

{% endcode %}

#### **광고 요청 예제 (web)**

{% code lineNumbers="true" %}

```json
{
	"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"
   }
}
```

{% endcode %}

## **4. 광고 응답**

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

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

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

### **Macro 적용 후 트래킹 URL 호출**

{% hint style="info" %}
Response 에 nurl, clickurl, adm 속성값에 아래를 Macro 가 포함된 경우 이를 대체하여 응답합니다.
{% endhint %}

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

#### **광고 응답 예제**

{% code lineNumbers="true" %}

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

{% endcode %}

### **쿠키매칭**

{% hint style="warning" %}
웹은 별도의 프로세스를 통해서 광고 오디언스 매칭을 수행합니다.
{% endhint %}

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

### **광고 서버 에러 코드 정의**

| 코드 | 설명                           |
| -- | ---------------------------- |
| 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 이상)**

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

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

### **광고요청 추가내용 (SKAdNetwork)**

> BidRequest / imp / banner / ext / skadn

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

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

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

#### **SKAdNetwork 광고 요청 예제**

{% code lineNumbers="true" %}

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

{% endcode %}

#### **광고응답 추가내용 (SKAdNetwork)**

> BidResponse / imp / banner / ext / skadn

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

#### **SKAdNetwork 광고 응답 예제**

{% code lineNumbers="true" %}

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

{% endcode %}