> 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-dsp/banner.md).
# 배너 광고
## 1. **REQUEST**
{% hint style="info" %}
SSP :arrow\_right: DSP
{% endhint %}
CJ 메조미디어 SSP 는 HTTP POST 방식으로 아래 정의된 객체를 JSON 형태로 작성해 DSP 인터페이스를 호출합니다. 요청 객체 정의는 [OPEN RTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) 규격을 따릅니다.
### **Request object**
| 필드 | 유형 | 필수 | 설명 |
| ------ | ------------ | -- | ------------------------------------------------ |
| id | string | Y | 요청 유니크 아이디 |
| cur | string array | N | ISO-4217-alpha 경매에 사용할 수 있는 통화 입니다. 예: “KRW” |
| test | integer | N | 경매가 테스트 모드(1)건 실시간 모드(0)건, 테스트 경매에는 입찰할 수 없습니다 |
| site | object | Y | [`Site`](#site) 객체를 참고하십시오. |
| app | object | Y | [`App`](#app) 객체를 참고하십시오. |
| device | object | Y | [`Device`](#device) 객체를 참고하십시오. |
| user | object | Y | [`User`](#user) 객체를 참고하십시오. |
| imp | object array | Y | [`Imp`](#imp) 객체를 참고하십시오. |
| 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의 번들이나 패키지명을 차단합니다. |
| ext | object | N | [`Ext`](#ext) 객체를 참고하십시오. |
### **Site**
| 필드 | 유형 | 필수 | 설명 |
| --------- | ------------ | -- | ------------------------------------- |
| id | string | Y | 퍼블리셔 ID |
| name | string | N | 애플리케이션 이름 |
| domain | string | N | 사이트 도메인 |
| page | string | N | 페이지 url |
| ref | string | N | 현재페이지로 이동해오기 바로 전 페이지의 주소 |
| cat | string array | N | 카테고리 |
| publisher | object | Y | [`Publisher`](#publisher) 객체를 참고하십시오. |
### **App**
| 필드 | 유형 | 필수 | 설명 |
| --------- | ------------ | -- | ------------------------------------- |
| id | string | Y | 퍼블리셔 ID |
| name | string | N | 애플리케이션 이름 |
| bundle | string | Y | 번들 이름, 패키지 이름 |
| storeurl | string | N | 앱스토어 URL |
| cat | string array | N | 카테고리 |
| publisher | object | Y | [`Publisher`](#publisher) 객체를 참고하십시오. |
### **Publisher**
> * [`Site`](#site) / publisher
> * [`App`](#app) / publisher
| 필드 | 유형 | 필수 | 설명 |
| ------------- | ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Y | 퍼블리셔 ID |
| name | string | N | 퍼블리셔 명 |
| domain | string | N | 사이트 도메인 |
| product\_attr | string | N | 광고상품코드
- 1: 띠배너
- 2: 전면배너
- 6: 정사각형 및 직사각형
- 7: 스카이스크래퍼
- 8: 리더보드
- 12: 스플래시
|
### **Device**
| 필드 | 유형 | 필수 | 설명 |
| ----- | ------- | -- | ----------------------------------------------------------------- |
| adid | string | Y | 디바이스의 ADID |
| make | string | Y | 디바이스의 제조사
예) samsung
|
| ua | string | Y | 디바이스의 User Agent 정보 |
| dnt | integer | N | 위치 추적 금지 활성화 여부
|
| ip | string | Y | IPV4 주소 |
| model | string | N | 모델명 |
| os | string | Y | 운영체제. 예) iOS, Anroid |
| osv | string | Y | 운영체제 버전. 예) 8.1, 9.2 |
| js | integer | N | RTB 프로토콜에 1로 정의되어 있습니다. |
| ifa | string | Y | Apple IFA 또는 Google 의 ADID |
### **User**
{% hint style="info" %}
RTB 프로토콜에는 없는 CJ 메조미디어의 확장 필드 입니다.
{% endhint %}
| 필드 | 유형 | 필수 | 설명 |
| -- | ------ | -- | ---------- |
| id | string | Y | 사용자의 고유 ID |
### **Imp**
| 필드 | 유형 | 필수 | 설명 |
| ----------------- | ------- | -- | ------------------------------------------------------------------------------------------------------------------------- |
| id | string | Y | 노출에 대한 유니크 아이디 |
| bidfloor | float | Y | 입찰로 인정받을 수 있는 최소 가격. 예) 4.12 |
| bidfloorcur | string | Y | 통화, 예) ‘KRW’ |
| secure | integer | Y | |
| type | string | Y | BANNER |
| banner | object | Y | [`Banner`](#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`](#imp) / banner
| 필드 | 유형 | 필수 | 설명 |
| -- | ------- | -- | --------- |
| w | integer | Y | 배너의 가로 크기 |
| h | integer | Y | 배너의 세로 크기 |
### **Ext**
{% hint style="info" %}
RTB 프로토콜에는 없는 CJ 메조미디어의 확장 필드 입니다.
{% endhint %}
| 필드 | 유형 | 필수 | 설명 |
| ------------ | ------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| price\_type | integer | N | |
| click\_macro | integer | N | 1: DSP매체에서 ADM내부에 클릭 Tracking을 받을 수 있는 매크로${MEZZO\_CLICK\_URL}을 제공해야 합니다.
DSP에서 click이 이루어질 때, 매크로로 치환된 click url를 발생시켜야 합니다.
|
### **요청 예제**
{% tabs %}
{% tab title="APP" %}
{% code lineNumbers="true" %}
```json
{
"id": "55d9d872-6129-497d-8187-46ffea622dbe$1278072412$KKHSVVWN",
"test": 1,
"cur": "USD",
"source": {
"ext": {
"schain": {
"ver": "1.0",
"nodes": [
{
"asi": "mman.kr",
"sid": "31998",
"rid": "55d9d872-6129-497d-8187-46ffea622dbe$1278072412$KKHSVVWN",
"hp": 1
}
],
"complete": 1
}
}
},
"regs": {
"ext": {
"us_privacy": "1---"
}
},
"tmax": 320,
"at": 2,
"imp": [
{
"tagid": "805013_com.test.mezzo",
"secure": 0,
"clickbrowser": 1,
"displaymanager": "ManSDK",
"displaymanagerver": "200",
"instl": 0,
"banner": {
"w": 320,
"h": 50,
"api": [
1,
2
]
},
"ext": {},
"bidfloorcur": "USD",
"bidfloor": 0.0008411677387431965,
"id": "166330331300"
}
],
"app": {
"publisher": {
"id": "31998",
"name": "test-pub-app-name",
"product_attr": 1
},
"id": "805013_com.test.mezzo",
"name": "test-pub-app-name",
"bundle": "com.test.mezzo",
"storeurl": "https://play.google.com/store/apps/details?id=com.mz.mezzomediaapp",
"cat": [
"IAB9"
]
},
"user": {
"id": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1"
},
"device": {
"geo": {
"country": "KOR"
},
"adid": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1",
"ifa": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1",
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 9; SM-G955N Build/PPR1.180610.011; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/105.0.5195.79 Mobile Safari/537.36",
"ip": "58.231.40.30",
"make": "samsung",
"os": "Android",
"osv": "9",
"model": "SM-G955N",
"language": "ko",
"js": 1,
"devicetype": 1,
"ext": {
"gain": "2d634ecd-c577-48bd-a76c-10ca1ad1abe1"
}
},
"ext": {
"request_time": 1663303313,
"price_type": 0
}
}
```
{% endcode %}
{% endtab %}
{% tab title="WEB" %}
{% code lineNumbers="true" %}
```json
{
"id": "b2b7e6c7-585b-45de-b55a-f219611c3cc6$1277829435$KKHSVVWN",
"test": 1,
"cur": [
"USD"
],
"source": {
"ext": {
"schain": {
"ver": "1.0",
"nodes": [
{
"asi": "mman.kr",
"sid": "31998",
"rid": "b2b7e6c7-585b-45de-b55a-f219611c3cc6$1277829435$KKHSVVWN",
"hp": 1
}
],
"complete": 1
}
}
},
"regs": {
"ext": {
"us_privacy": "1---"
}
},
"tmax": 320,
"at": 2,
"imp": [
{
"tagid": "805013_com.test.mezzo",
"secure": 0,
"instl": 0,
"banner": {
"w": 320,
"h": 50,
"api": [
1,
2
]
},
"ext": {},
"bidfloorcur": "USD",
"bidfloor": 0.0008411677387431965,
"id": "166330623100"
}
],
"site": {
"publisher": {
"id": "31998",
"name": "test-pub-site-name",
"domain": "com.test.mezzo",
"product_attr": 1
},
"id": "805013_com.test.mezzo",
"name": "test-pub-site-name",
"domain": "com.test.mezzo",
"page": "http://mtagdev.mman.kr:9300/V2/banner_step2.html",
"ref": "http://mtagdev.mman.kr:9300/",
"mobile": 1,
"cat": [
"IAB9"
]
},
"user": {
"id": "4fbf0ac3-63bb-43c5-83ab-418ea1fe0a12"
},
"device": {
"geo": {
"country": "KOR"
},
"adid": "4fbf0ac3-63bb-43c5-83ab-418ea1fe0a12",
"ifa": "",
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 9; SM-G955N Build/PPR1.180610.011; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/105.0.5195.79 Mobile Safari/537.36",
"ip": "58.231.40.30",
"make": "samsung",
"os": "Android",
"osv": "9",
"model": "SM-G955N",
"language": "ko",
"js": 1,
"devicetype": 1
},
"ext": {
"request_time": 1663306231,
"price_type": 0
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
##
## **2. RESPONSE**
{% hint style="info" %}
DSP :arrow\_right: SSP
{% endhint %}
DSP 는 아래 정의된 객체를 HTTP body 에 포함해 응답합니다. 객체 정의는 [OPEN RTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) 규격을 따릅니다.
### **Bid Response**
{% hint style="info" %}
JSON 형식의 응답 객체입니다.
{% endhint %}
| 필드 | 유형 | 필수 | 설명 |
| ------- | ------------ | -- | -------------------------------------------------------------------------------------- |
| id | string | Y | Bid Request 의 ID |
| bidid | string | Y | Bid 오브젝트의 ID |
| cur | string | Y | 입찰시 사용할 통화. 예) KRW |
| seatbid | object array | Y | Seatbid 객체 배열입니다.
입찰이 이루어지려면 1+가 필요합니다.
|
### **Seatbid**
| 필드 | 유형 | 필수 | 설명 |
| ---- | ------------ | -- | ------------------------------------------------------------------------------ |
| seat | string | Y | 입찰 정보를 관리하는 ID |
| bid | object array | Y | Bid 객체 배열입니다.
입찰이 이루어지려면 1+가 필요합니다.
|
### **Bid**
| 필드 | 유형 | 필수 | 설명 |
| ------- | ------------- | -- | ---------------------------------------------------------------------------------- |
| id | string | Y | 입찰 정보를 관리하는 ID |
| impid | string | Y | 입찰 요청의 노출과 관련된 노출 ID입니다.
입찰 요청 노출 객체 ID와 반드시 일치해야 합니다.
|
| price | float | Y | 입찰 가격 |
| cat | string array | Y | 카테고리 |
| nurl | string | N | 낙찰 알림 url (win URL)
낙찰가를 {AUCTION\_PRICE} 매크로에 치환하여 전달합니다.
|
| burl | string | N | 낙찰 청구 알림 url (Billing notice URL)
낙찰가를 {AUCTION\_PRICE} 매크로에 치환하여 전달합니다.
|
| lurl | string | N | 유찰 알림 url (Loss notice URL)
{AUCTION\_LOSS} 매크로에 유찰 사유 코드를 치환하여 전달합니다.
|
| adm | string (html) | Y | [`ADM`](#adm) 객체를 참고하십시오. |
| iurl | string | Y | 노출 image URL |
| adomain | string array | Y | 블랙리스트를 검사하는 광고주 도메인 |
| cid | string | Y | 광고주 캠페인명 / id |
| crid | string | Y | 광고주 광고물명 / id |
| w | integer | Y | 광고 사이즈 |
| h | integer | Y | 광고 사이즈 |
| ext | string | Y | 확장 영역 |
### **ADM**
{% hint style="info" %}
개행문자와 공백이 없는 html입니다.
{% endhint %}
### **응답 예제**
{% tabs %}
{% tab title="success" %}
{% code lineNumbers="true" %}
```json
{
"id": "ece5c105-dd24-468f-8392-d624b8d49953",
"seatbid": [
{
"bid": [
{
"id": "58eb3071faff4576320e4fe9",
"impid": "149015951000",
"price": 50,
"cat": ["iab1", "iab2", "iab2"],
"nurl": "win url",
"adm": "...",
"iurl": "image.jpg",
"adomain":["advertiserdomain.com"],
"cid": "80",
"crid": "188",
"h": 50,
"w": 320,
"ext": {}
}
],
"seat": "dsp id"
}
],
"bidid": "dsp",
"cur": "KRW"
}
```
{% endcode %}
{% endtab %}
{% tab title="noad" %}
{% code lineNumbers="true" %}
```json
{
"id": "",
"seatbid": [],
"bidid": "mezzo",
"cur": "KRW"
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
##
## **3. SKAdNetwork 지원(iOS14 이상)**
{% hint style="info" %}
해당 내용은 iOS14 버전 혹은 그 이상의 환경에서 SKAdNetwork가 활성화된 캠페인을 지원하기 위한 내용입니다.
{% endhint %}
| |
|---|
| 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를 CJ MezzoMedia 담당자에게 전달하고
CJ 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에 등록되어 있어야 한다. |
|---|
| 1 | DSP에서 제공하는 SKAdNetwork ID가 퍼블리셔의 info.plist에 등록되어 있어야 한다. |
| 2 | 사용자 기기의 운영체제가 iOS14 혹은 그 이상이어야 한다. |
| 3 | SKAdNetwork를 지원하는 버전의 SDK를 설치해야한다. |
| 4 | DSP는 CJ 메조미디어의 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)**
{% hint style="info" %}
BidResponse / imp / banner / ext / skadn
{% endhint %}
| 필드 | 유형 | 필수 | 설명 | 예 |
| ---------- | ------ | -- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| 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…” |
### **예제**
{% tabs %}
{% tab title="요청" %}
{% code lineNumbers="true" %}
```json
{
"imp":[{
"ext": {
"skadn": {
"version": "2.0",
"sourceapp": "000000000",
"skadnetids": ["feyaarzu9v.skadnetwork", "8sRFag4vVC.skadnetwork"]
}
}
}]
}
```
{% endcode %}
{% endtab %}
{% tab title="응답" %}
{% 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 %}