SSP Banner AD. Request API

10 분 소요

Geonjin Mun

REQUEST

SSP DSP

메조미디어 SSP 는 HTTP POST 방식으로 아래 정의된 객체를 JSON 형태로 작성해 DSP 인터페이스를 호출합니다.
요청 객체 정의는 OPEN RTB 2.5 규격을 따릅니다.

request object

필드	유형	필수	설명
id	string	Y	요청 유니크 아이디
cur	string array	N	ISO-4217-alpha 경매에 사용할 수 있는 통화 입니다. 예: “KRW”
test	integer	N	경매가 테스트 모드(1)건 실시간 모드(0)건, 테스트 경매에는 입찰할 수 없습니다
site	object	Y	site 객체를 참고하십시오.
app	object	Y	app 객체를 참고하십시오.
device	object	Y	device 객체를 참고하십시오.
user	object	Y	user 객체를 참고하십시오.
imp	object array	Y	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 객체를 참고하십시오.

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 객체를 참고하십시오.

app

필드	유형	필수	설명
id	string	Y	퍼블리셔 ID
name	string	N	애플리케이션 이름
bundle	string	Y	번들 이름, 패키지 이름
storeurl	string	N	앱스토어 URL
cat	string array	N	카테고리
publisher	object	Y	publisher 객체를 참고하십시오.

publisher

site / publisher
app / publisher

필드	유형	필수	설명
id	string	Y	퍼블리셔 ID
name	string	N	퍼블리셔 명
domain	string	N	사이트 도메인
product_attr	string	N	광고상품코드 1: 띠배너 2: 전면

device

필드	유형	필수	설명
adid	string	Y	디바이스의 adid정보
make	string	Y	운영체제. 예) iOS, Anroid
ua	string	Y	디바이스의 User Agent 정보
dnt	integer	N	위치 추적 금지 활성화 여부. 0: 추적 가능, 1: 추적 금지.
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

RTB 프로토콜에는 없는 메조미디어의 확장 필드 입니다.

필드	유형	필수	설명
id	string	Y	사용자의 고유 ID

imp

필드	유형	필수	설명
id	string	Y	노출에 대한 유니크 아이디
bidfloor	float	Y	입찰로 인정받을 수 있는 최소 가격. 예) 4.12
bidfloorcur	string	Y	통화, 예) ‘KRW’
secure	integer	Y	0 : http, 1 : https
type	string	Y	BANNER
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 버전을 의미합니다.

imp / banner

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

ext

RTB 프로토콜에는 없는 메조미디어의 확장 필드 입니다.

필드	유형	필수	설명
price_type	integer	N	0:CPM, 2: CPC
click_macro	integer	N	1:DSP매체에서 ADM내부에 클릭 Tracking을 받을 수 있는 매크로${MEZZO_CLICK_URL}을 제공해야 합니다. DSP에서 click이 이루어질 때, 매크로로 치환된 click url를 발생시켜야 합니다.

요청 예제 (APP)

{
  "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": "31998_%EC%9D%B4%EA%B2%83%EC%9D%B4 %ED%85%8C%EC%8A%A4%ED%8A%B8",
      "product_attr": 1
    },
    "id": "805013_com.test.mezzo",
    "name": "805013_%EC%9D%B4%EA%B2%83%EC%9D%B4 %ED%85%8C%EC%8A%A4%ED%8A%B8",
    "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
  }
}

요청 예제 (WEB)

{
  "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": "31998_com.test.mezzo",
      "domain": "com.test.mezzo",
      "product_attr": 1
    },
    "id": "805013_com.test.mezzo",
    "name": "805013_com.test.mezzo",
    "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 10; SM-G981B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Mobile Safari/537.36",
    "ip": "203.248.117.195",
    "make": "",
    "os": "Android",
    "osv": "",
    "model": "",
    "language": "ko",
    "js": 1,
    "devicetype": 1
  },
  "ext": {
    "request_time": 1663306231,
    "price_type": 0
  }
}

RESPONSE

DSP SSP

DSP 는 아래 정의된 객체를 HTTP body 에 포함해 응답합니다.
객체 정의는 OPEN RTB 2.5 규격을 따릅니다.

Bid Response

JSON 형식의 응답 객체입니다.

필드	유형	필수	설명
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 객체를 참고하십시오.
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

개행문자와 공백이 없는 html입니다..

Bid response 예제

{
  "id": "ece5c105-dd24-468f-8392-d624b8d49953",
  "seatbid": [
    {
      "bid": [
        {
          "id": "58eb3071faff4576320e4fe9",
          "impid": "149015951000",
          "price": 50,
          "cat": ["iab1", "iab2", "iab2"],
          "nurl": "win url",
          "adm": "<html>...</html>",
          "iurl": "image.jpg",
          "adomain":["advertiserdomain.com"],
          "cid": "80",
          "crid": "188",
          "h": 50,
          "w": 320,
          "ext": {}
        }
      ],
      "seat": "dsp id"
    }
  ],
  "bidid": "dsp",
  "cur": "KRW"
}

Bid response(noad) 예제

{
  "id": "",
  "seatbid": [],
  "bidid": "mezzo",
  "cur": "KRW"
}

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