> For the complete documentation index, see [llms.txt](https://docs.targetpick.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.targetpick.io/for-ssp/banner.md).

# 배너 광고

## **1. REQUEST**

아래 내용을 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**

| 필드        | 유형           | 필수 | 설명                                                                              |
| --------- | ------------ | -- | ------------------------------------------------------------------------------- |
| ssp\_id   | string       | Y  | SSP ID (TARGETPICK 에서 발급)                                                       |
| id        | string       | Y  | 요청 유니크 아이디                                                                      |
| cur       | string array | N  | <p>ISO-4217-alpha 경매에 사용할 수 있는 통화 입니다. <br>예: “KRW”</p>                         |
| imp       | object array | Y  | [`imp`](#imp) 객체를 참고하십시오.                                                       |
| site      | object       | Y  | [`site`](#site) 객체를 참고하십시오.                                                     |
| app       | object       | Y  | [`app`](#app) 객체를 참고하십시오.                                                       |
| publisher | object       | Y  | [`publisher`](#publisher) 객체를 참고하십시오.                                           |
| device    | object       | Y  | [`device`](#device) 객체를 참고하십시오.                                                 |
| user      | object       | Y  | [`user`](#user) 객체를 참고하십시오.                                                     |
| at        | integer      | Y  | <ul><li>0: fixed price</li><li>1: first price</li><li>2: second price</li></ul> |
| 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  | <ul><li>0: http</li><li>1: https</li></ul>                                                                                 |
| banner            | object  | Y  | [`banner`](#banner) 객체를 참고하십시오.                                                                                            |
| instl             | integer | Y  | <p>전면광고 여부를 전달합니다. (default : 0)</p><ul><li>1: the ad is interstitial or full screen</li><li>0: not interstitial</li></ul> |
| displaymanager    | string  | Y  | SSP 플랫폼명 또는 SDK명을 의미합니다.                                                                                                   |
| displaymanagerver | string  | Y  | SSP 플랫폼 또는 SDK 버전을 의미합니다.                                                                                                  |

### **Banner**

> [imp](https://docs.meba.kr/s-plus/api/dsp/delivery/banner/#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 |

{% 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**

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

### **요청 예제**

{% tabs %}
{% tab title="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 %}
{% endtab %}

{% tab title="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 %}
{% endtab %}
{% endtabs %}

##

## **2. RESPONSE**

OPEN RTB 2.5 규격의 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 호출**

{% 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>

### **응답 예제**

{% tabs %}
{% tab title="Response" %}
{% 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 %}
{% endtab %}
{% endtabs %}

##

## **3. 쿠키매칭**

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

<table data-header-hidden><thead><tr><th width="85"></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 참조   |

##

## **4. SKAdNetwork 지원(iOS14 이상)**

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

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

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

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

> BidResponse / imp / banner / ext / skadn

| 필드         | 유형     | 필수 | 설명                                                                                 | 예                                               |
| ---------- | ------ | -- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| version    | string | Y  | 사용하는 SKadNetwork 버전. “2.0” 혹은 그 이상.                                                | “version”:”2.0”                                 |
| network    | string | Y  | <p>광고 네트워크 식별자.<br>Request에 포함된 skadnetids와 최소 한 개는 매칭되어야 함</p>                    | “network”:\[“feyaarzu9v.skadnetwork”]           |
| campaign   | string | Y  | <p>Apple의 규격에 맞는 캠페인 ID.<br>1과 100 사이의 정수를 이용해서 표현해야함</p>                          | “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  | <p>Apple App 스토어에 등록된 퍼블리셔 App ID.<br>‘BidRequest.imp.ext.skad.sourceapp’ 과 매칭</p> | “sourceapp”:”000000000”                         |
| timestamp  | string | Y  | Unix time을 string 값으로 전달                                                           | “timestamp”:”1234567890”                        |
| signature  | string | Y  | Apple에서 제공하는 SKAdNetwork sigature 값                                                | “signature”:”ABCDEFGHijkl-lmb…”                 |

### **예제**

{% tabs %}
{% tab title="Request" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% 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 %}
{% endtab %}
{% endtabs %}