Bid Specification

kakao RTB Bid 요청과 응답 상세 스펙입니다.

1. Bid Request Specification

Object Model

OpenRTB 스펙과 동일 (OpenRTB 스펙 3.1 Object Model 참고)

1-1. Object Specifications

Object : Bid Request

Attribute	Type	Description	kakao Description
id	string; required	BidRequest의 고유 ID값	해당 값은 Bid Response의 “id”와 매핑됩니다
imp	object array; required	Object: Imp 참조
site	object; recommended	Object : Site 참조
app	object; recommended	Object : App 참조
device	object; recommended	Object : device 참조
user	object; recommended	Object : user 참조
test	integer	0=live mode, 1= test mode	0
at	integer	1 = First Price, 2 = Second Price	1
tmax	integer	Maximum time in milliseconds to submit a bid to avoid timeout.	180 (별도 협의 사항)
cur	string array	Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes.	KRW
bcat	string array	Blocked advertiser categories using the IAB content categories.
badv	string array	Block list of advertisers by their domains (e.g., “ford.com”)
ext	object

Object : Regs

Attribute	Type	Description	kakao Description
coppa	integer	Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.	coppa=1인 앱의 경우 adid 전달되지 않음
ext	object	Placeholder for exchange-specific extensions to OpenRTB.

Object : Imp

Attribute	Type	Description	kakao Description
id	string; required	A unique identifier for this impression within the context of the bid request	단일 imp.id를 통해 Multi-Ad-Format을 지원합니다 (Banner Object & Native Object)
banner	object	Object : Banner 참조
native	object	Object : Native 참조
displaymanager	string	Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile).	카카오 SDK를 심은 경우 “adfit”으로 전달함
displaymanagerver	string	Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile).
tagid	string	Identifier for specific ad placement of ad tag that was used to initiate the auction
bidfloor	float	Minimum bid for this impression expressed in CPM.
bidfloorcur	string	Currency specified using ISO-4217 alpha code	KRW만 지원
secure	integer	0=non-secure, 1=secure.
ext	object

Object : Banner

Attribute	Type	Description	kakao Description
format	object array; recommended	Object: format 참조	다중 사이즈 송출 가능한 지면 요청 시 사용
w	integer	Exact width in device independent pixels.
h	integer	Exact height in device independent pixels
battr	Integer array	Block creative attributes.	6,7
id	string	Unique identifier for this banner object.
ext	object

Object : Video

Video 연동의 경우, Video 대상 DSP 분리가 필요할 수 있습니다.

Attribute	Type	Description	kakao Description
mimes	string array	Content MIME types supported	Video/mp4 만 가능
minduration	integer	Minimum video ad duration in seconds	>=0
maxduration	integer	Maximum video ad duration in seconds	>0
protocols	integer array	An array of video protocols the publisher can accept in the vid response.	Vast3.0만 지원
w	integer	Width of the video player in device independent pixels (DIPS)
h	integer	Height of the video player in device independent pixels (DIPS)
startdelay	integer	Indicates the start delay in seconds for per-roll, mid-roll, or post-roll ad placements.	Pre-roll, mid-roll만 지원됨
placement	integer	Placement type for the impression	1
skip	integer	0=no, 1=yes
skipafter	integer	Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable	5/15
sequence	integer	If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives	1
linearity	integer	Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed.	1 (Linear/In-Stream)
delivery	integer array	Supported delivery methods.	[2] (progressive)
ext	object

Object : Native

Attribute	Type	Description	kakao Description
request	string; required	Request payload complying with the Native Ad Specification.
ver	string; recommended	Version of the Dynamic Native Ads API to which request complies	1.2
ext	object

Object : Format

Attribute	Type	Description	kakao Description
w	integer	Width in device independent pixels
h	integer	Height in device independent pixels

Object : Site

Attribute	Type	Description	kakao Description
id	string	Exchange-specific site Id.
domain	string	Domain of the site (e.g., “mysite.foo.com”).
cat	string array	Array of IAB content categories of the site.
page	string	URL of the page where the impression will be shown
publisher	object	Object : Publisher 참조
content	object	Object : Content 참조
ext	object

Object : App

다음 앱은 web 환경으로 (하이브리드 앱) App Object가 아닌 Site Object만 전달됩니다.

Attribute	Type	Description	kakao Description
id	string	Exchange-specific site Id.
bundle	string	A platform-specific application identifier intended to be unique to the app and independent of the exchange( Android: bundle or package name/ iOS : typically a numeric ID)
storeurl	string	App store URL for an installed app
cat	string array	Array of IAB content categories of the app.
publisher	object	Object : Publisher 참조
content	object	Object : Content 참조
ext	object

Object : Publisher

Attribute	Type	Description	kakao Description
id	string	Exchange-specific publisher ID	Partner User ID, partner_id
name	string	Publisher name	One of the following -“DAUM”: daum.net -“TALK”: Kakao Talk -“STORY”: Kakao Story -“KAKAO_SERVICE”: Other kakao Service -“GENERAL”: Other publishers that joined to kakao’s SSP server, “ADFIT”
domain	string	Highest level domain of the publisher
ext	object

Object : Content

Attribute	Type	Description	kakao Description
id	string	ID uniquely identifying the content
title	string	Content Title	”
livestream	integer	0=not live 1=content is live
len	integer	Length of content in seconds	영상 길이 (live인 경우 null)
cat	string array	IAB content category

Object : Device

Attribute	Type	Description	kakao Description
ua	string; recommended	Browser user agent string
sua	UserAgent object	Structured user agent information defined by a UserAgent object (Object : UserAgent 참조)
dnt	integer; recommended	0= tracking is unrestricted, 1=do not track
lmt	integer; recommended	0=tracking is unrestricted, 1=tracking must be limited per commercial guidelines
ip	string; recommended	IPv4 address closet to device	Ip는 3옥텟 까지 제공됩니다.
make	string	Device make (e.g., “Apple”).
model	string	Device model (e.g., “iPhone”).
os	string	Device operating system (e.g., “iOS”).
osv	string	Device operating system version (e.g., “3.1.2”)
hwv	string	Hardware version of the device (e.g., “5S” for iPhone 5S).
h	integer	Physical height of the screen in pixels
w	integer	Physical width of the screen in pixels
ppi	integer	Screen size as pixels per linear inch
pxratio	float	The ratio of physical pixels to device independent pixels
language	string	Browser language using ISO-639-1-alpha-2.
ifa	string	ID sanctioned for advertiser use in the clear
ext	object

Object : User

Attribute	Type	Description	kakao Description
id	string; recommended	Exchange-specific ID for the user.	Partner User ID, partner-uid(cookie matching)
ext	object

Object : UserAgent

Attribute	Type	Description	kakao Description
browsers	array of BrandVersion objects; recommended	Each BrandVersion object (Object : BrandVersion 참조) identifies a browser or similar software component. Implementers should send brands and versions derived from the Sec-CH-UA-Full-Version-List header*.
platform	BrandVersion object; recommended	A BrandVersion object (Object : BrandVersion 참조) that identifies the user agent’s execution platform / OS. Implementers should send a brand derived from the Sec-CH-UA-Platform header, and version derived from the Sec-CH-UAPlatform-Version header *.
mobile	integer	1 if the agent prefers a “mobile” version of the content, if available, i.e. optimized for small screens or touch input. 0 if the agent prefers the “desktop” or “full” content. Implementers should derive this value from the Sec-CH-UAMobile header *.
model	string	Device model. Implementers should retrieve this value from the Sec-CH-UAModel header*.
ip	integer	The source of data used to create this object, List: User-Agent Source in AdCOM 1.0

Object : BrandVersion

Attribute	Type	Description	kakao Description
brand	string; required	A brand identifier, for example, “Chrome” or “Windows”. The value may be sourced from the User-Agent Client Hints headers, representing either the user agent brand (from the Sec-CH-UA-Full-Version header) or the platform brand (from the Sec-CH-UA-Platform header).
version	string array	A sequence of version components, in descending hierarchical order (major, minor, micro, …)

1-2. Native Ad Request Markup Details

Native Specification version 1.1 기준으로 요청됨

Object : Native Markup Request

Attribute	Required	Type	Default	Description	kakao Description
plcmtcnt		integer		The number of identical placements in this Layout.
assets	필수	array of objects		Object : Assets 참조
ext		object

Object : Asset

Attribute	Required	Type	Default	Description	kakao Description
id	필수	integer		Unique asset ID, assigned by exchange
required		integer	0	1= Required
title	권장	object		Object : Title 참조
img	권장	object		Object : Image 참 조
video		object		Object : video 참 조
data	권장	object		Object : Data 참조
ext		object

Object : Title

Attribute	Required	Type	Default	Description	kakao Description
len	필수	integer		Maximum length of the text in the title element
ext		object

Object : Image

Attribute	Required	Type	Default	Description	kakao Description
type		integer		Type ID of the image element supported by the publisher	1: 프로필 이미지 (300x300) 2 : Logo 3 : Main Image 701 : 동영상 엔드캡 이미지 (1280x720) 702: 배너 이미지 (비즈보드 사용) 703 : Opt-Out
w		integer		Width of the image in pixels
h		integer		Height of the image in pixels
ext		object

Object : Video

Attribute	Required	Type	Default	Description	kakao Description
mimes		Array of string		Content MIME types supported	Video/mp4만 가능
minduration		integer		Minimum video ad duration in seconds	>=0
maxduration		integer		Maximum video ad duration in seconds	>0
protocols		integer[]		An array of video protocols the publisher can accept in the vid response.	Vast3.0만 지원
w		integer		Width of the video player in device independent pixels (DIPS).
h		integer		Height of the video player in device independent pixels (DIPS).

Object : Data

Attribute	Required	Type	Default	Description	kakao Description
type	필	integer		Type ID of the element supported by the publisher	1: 프로필명 (20자) 2: 광고 문구 (45자) 12 : CTAtext (6자) *CTA는 추가 협의 필 요 701 : 소재 설명 (45자)
len		integer		Maximum length of the text in the elements response
ext		object

2. Bid Respose Specification

Object Model

OpenRTB 스펙과 동일 (OpenRTB 스펙 4.2 Object Model 참고)

2-1. Object Specification

Object : Bid Response

Attribute	Type	Description	kakao Description
id	string; required	Id of the bid request to which this is a response
seatbid	object array	Array ot seatbid objects’ 1+required if a bid is to be made.	단일 seatbid만 처리 가능합니다.
bidid	string	Bidder generated response ID to assist with logging/tracking
cur	string	Bid currency using ISO-4217 aplha codes	KRW
nbr	integer	Reason for not bidding
ext	object

Object : Seatbid

Attribute	Type	Description	kakao Description
bid	object array; required	Object : bid 참조 Array of 1+ bid objects each related to an impression.	native.plcmtcnt 이하의 광고 응답 수에 대해 처리 가능.
seat	string	ID of the buyer seat on whose behalf this bid is made.
ext	object

Object : Bid

Attribute	Type	Description	kakao Description
id	string; required	Bidder generated bid ID to assist with logging/tracking
impid	string; required	ID of the Imp object in the related bid request
price	float; required	Bid Price expressed as CPM although the actual transaction is for a unit impression only.
nurl	string	Win notice URL called by the exchange if the bid wins.
lurl	string	Loss notice URL called by the exchange when a bid is known to have been lost.	${AUCTION_MIN_TO_WIN}, ${AUCTION_LOSS} 지원
adm	string; required	Optional means of conveying ad markup in case the bid wins.	완전한 HTML만 지원함 * video 응답은, 360p/720p 2종류의 영상 파일이 응답 되어야 합니다.
adid	string; required	ID of a preloaded ad to be served if the bid wins.
adomain	string arrary; required	Advertiser domain for block list checking
cid	string; required	Campaign ID to assist with ad quality checking
crid	string; required	Creative ID to assist with ad quality checking
cat	string arrary; required	IAB content categories of the creative.
w	integer; required	Width of the creative in device independent pixels
h	integer; required	Height of the creative in device independent pixels
ext	object

2-2. Native Ad Response Markup Details

Object : Native Markup Response

Attribute	Required	Type	Default	Description	kakao Description
assets	필수	array of objects		Object : Asset 참 조
linkg	필수	object		Object : Link 참조 Destination Link. This is default link object for the ad. Individual assets can also have a link object which applies if the asset is activated. If the asset doesn’t have a link object , the parent link object applies
imptrackers	필수	array of objects		Array of impression tracking URLs, expected to return a 1x1 image	최대 5개까지만 응답 가능.
ext		object			object : ext 참조

Object : Asset

Attribute	Required	Type	Default	Description	kakao Description
id	필수	integer		Unique asset ID, assigned by exchange, must match one of the asset IDs in request
title		object		Object : Title 참조
img		object		Object : img 참조	request.native.assets.img.type : 703 (opt-out)이 필수로 요청 시, opt-out icon/link를 동일 id 하위에 포함하여 전달 주어야 한다. <img.type:703 이 id:10 으로 필수 요청일 경우 sample> { \”id\”:10, \”img\”:{ \”url\”:\”admark- img.url\”, \”w\”:50, \”h\”:50 }, "link":{ \”url\”:\”admark- landing.url\” } }
link		object		Object : link 참조
video		object		Object : video 참조
data		object		Object : data 참조
ext		object

Object : Title

Attribute	Required	Type	Default	Description	kakao Description
text	필수	string		The text associated with the text element
ext		object

Object : Image

Attribute	Required	Type	Default	Description	kakao Description
url	필수	string		URL of the image asset.
w	필수	integer		Width of the image in pixels
h	필수	integer		Height of the image in pixels
ext		object

Object : Data

Attribute	Required	Type	Default	Description	kakao Description
value	필수	string		The formatted string of data to be displayed
ext		object

Object : Video

Attribute	Required	Type	Default	Description	kakao Description
vasttag	필수	string		vast xml	720p 영상 파일 응답 필요

Object : Link

Attribute	Required	Type	Default	Description	kakao Description
url	필수	string		Landing URL of the clickable link.
clicktrackers		Array of strings		List of Tracker URL to be fired on click of the URL	단일 Tracker URL만 응답 가능
ext		object

Object : Response.ext

Attribute	Required	Type	Default	Description	kakao Description
hidetrackers		Array of strings		이 광고 숨김 처리	비즈보드의 응답에 대 해서는 필수값. 숨김 처리 이벤트가 호출된 광고 단위에 대해, 해당 소재의 광 고 계정에 대해 24시 간동안 미 응답 처리 필요.