OpenRTB Native Ads API Specification Draft Version 0.99.11.

13

RTB Project

RTBProject
OpenRTBNativeAdsAPISpecification
Version1
November2014

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 1

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

Introduction
The Native Ads sub-committee of the IAB OpenRTB Project assembled in May 2014 to develop
a new supplementary API specification for companies interested in an open protocol for the
automated trading of Native Ads enabled media across a broader range of platforms, devices,
and advertising solutions. This document is the culmination of those efforts.
About the IABs Networks & Exchanges Committee:
The IAB Networks & Exchanges Committee is comprised of senior leaders of ad networks and
ad exchanges member companies. The committee is dedicated to furthering the interests of
digital ecosystem in today's complex ad marketplace. Committee objectives are to foster the
highest standards of professionalism and accountability in relationships with publishers,
advertisers, intermediaries, and the agency community, to develop programs that enable
revenue growth, and to create best practices that protect consumers and the industry.
The OpenRTB Project is a working group within the IAB Advertising Technology Council.

This document can be found at www.iab.net

IAB Contact Information:
Brendan Riordan-Butterworth
Director of Technical Standards, IAB
[email protected]

License
OpenRTB Specification by OpenRTB is licensed under a Creative Commons Attribution 3.0
License, based on a work at openrtb.info. Permissions beyond the scope of this license may be
available at http://openrtb.info. To view a copy of this license, visit
http://creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second
Street, Suite 300, San Francisco, CA 94105, USA.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 2

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

Table of Contents
Before You Get Started
1 Introduction
1.1 Mission / Overview
1.2 Credits / Project History
1.3 Resources
1.4 Version History
2 Native Ads Basics
2.1 IAB Core Six
2.2 Data Format
2.3 Versioning
2.4 Customization and Extensions
3 Bid Request Details
3.1 Native Object Hierarchy
4 Native Ad Request Markup Details
4.1 Native Markup Request Object
4.2 AssetObject
4.3 Title Object
4.4 Image Object
4.5 Video Object
4.6 Data Object
5 Native Ad Bid Response Markup
5.1 Native Ad Creative JSON
5.2 Native Object
5.3 Asset Object
5.4 Title Object
5.5 Image Object
5.6 Data Object
5.7 Video Object
5.8 Link Object

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 3

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

6 Bid Request/Response Samples

Bid Request
Bid Response
6.2 Chat List Example
Bid Request
Bid Response
6.3 Content Stream with Video Element Example
Bid Request
Bid Response
6.4 Google Text Ad
Bid Request
Bid Response
7 Reference Lists/Enumerations
7.1 Native Layout IDs
7.2 Native Ad Unit IDs
7.3 Data Asset Types
7.4 Image Asset Types
8 Implementation Notes
8.1 Multi Placement Bid Requests

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 4

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

Before You Get Started

This specification contains a detailed explanation of a sub-protocol of the OpenRTB real-time
bidding interface. Not all objects are required, and each object may contain a number of
optional parameters. To assist a first time reader of the specification, we have indicated
which fields are essential to support a minimum viable real time bidding interface for various
scenarios (banner, video, mobile, etc.).
A minimal viable interface should include the required and recommended parameters, but
the scope for these parameters may be limited to specific scenarios. In these cases, the scope
will be qualified with the applicable scenarios (e.g., required for native impressions and
recommended for native impressions). Conversely, if the scope is not qualified, it applies to
all scenarios.
Optional parameters may be included to ensure maximum value is derived by the parties.

IMPORTANT: Since recommended parameters are not required, they may not be available
from all supply sources. It is suggested that all parties to OpenRTB transaction complete the
integration checklist(please refer to OpenRTB 2.3) to identify which parameters the supply
side supports in the bid request, and which parameters the demand side requires for ad
decisioning.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 5

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

1 Introduction
1.1 Mission / Overview
The mission of the OpenRTB Native project is to spur standardization and greater growth in
the Real-Time Bidding (RTB) marketplace for Native Ads by providing open industry standards
for communication between buyers of advertising and sellers of publisher inventory.
This specification is a sub-protocol of OpenRTB 2.3 to allow for the delivery of native
advertising formats, as their specifics differ from publisher to publisher. In May 2013, a
separate IAB subcommittee has been formed to define the request and response structures of
native ad units.
Establishing a true open standard for this new format will be instrumental to native ads
adoption by app publishers and demand side platforms. With a common framework on the
buy-side, the industry as a whole will benefit from increased demand for native ad formats.

1.2 Credits / Project History

Neal Richter & Avinash Shahdadpuri, Rubicon Project
Jim Butler, Nexage
Adam Morgenlender & Gabor Cselle, Twitter
Narayanan Balakrishnan & Anand Narayanan, InMobi
Giuseppe Di Mauro, PubMatic
Ilya Kaplun, Visible Measures
Jennifer Lum, Adelphic
Wesley Biggs, Byyd
Benoit Grouchko & Elisabeth Rotrou, Criteo
David Hernandez, AOL
Rajaraman Periasamy, RocketFuel
Jin Yu, OpenX
Anton Roslov, Phorm
Andra Tori, Zemanta

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 6

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

1.3 Resources
Resource

Location

OpenRTB Website

http://openrtb.info

OpenRTB Native Ads Project Page

http://github.com/openrtb/OpenRTB/NativeAds.ht
ml

Developer / Product Manager Mailing

List

http://groups.google.com/group/openrtb-native

1.4 Version History

Version 0.99.10.24 PUBLIC DRAFT October 24, 2014
Version 0.99.10.27 PUBLIC DRAFT October 27, 2014

2 Native Ads Basics

Native advertising is an online advertising method in which the advertiser attempts to gain
attention by providing content in the context of the user's experience. Native ad formats
match both the form and function of the user experience in which it is placed. This is in
contrast to traditional banner or interstitials ads, which are displayed in a separate space of
predefined and universal size, without regard to their surroundings.

2.1 IAB Core Six

The IAB Native Advertising Playbook lists six types of native ad units:

In Feed Units
Paid Search Units
Recommendation Widgets
Promoted Listings
IAB Standard with Native Elements
Custom / Cant be contained

Some examples for native ad formats are shown below.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 7

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 8

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

2.2 Data Format

As this specification outlines an optional sub-protocol of the main OpenRTB protocol payload,
the format must follow that of its parent. Please refer to the main OpenRTB specification for
details of various formats that may be used

2.3 Versioning
The Native Object in the Bid Request (OpenRTB 2.3) contains a ver field defining the version
of the OpenRTB native extension.

2.4 Customization and Extensions

The OpenRTB Native Ads spec allows for exchange specific customization and extensions of the
specification. Any object may contain extensions. In order to keep extension fields consistent
across platforms, they should consistently be named ext.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 9

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

3 Bid Request Details

RTB transactions are initiated when an exchange or other supply source sends a bid request to
a bidder. The bid request consists of a bid request object, at least one impression object, and
may optionally include additional objects providing impression context.

3.1 Native Object Hierarchy

Following is the object hierarchy for a bid request. The new Native Object is another optional
element of the impression object, and can be specified as an alternative to or in conjunction
with a banner object or video object.

4 Native Ad Request Markup Details

4.1 Native Markup Request Object
The Native Object defines the native advertising opportunity available for bid via this bid
request. It must be included directly in the impression object if the impression offered for
auction is a native ad format.
The Default column dictates how optional parameters should be interpreted if explicit values
are not provided.
Field

Scope

Type

ver

required

integer

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Default
1

Description
Version of the Native Markup
version in use.

Page 10

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

layout

recommended

integer

The Layout ID of the native ad

unit. See the Table of Layout IDs
below.

adunit

recommended

integer

The Ad unit ID of the native ad

unit. This corresponds to one if
IAB Core-6 native ad units. See
the Table of Ad Unit IDs below.

plcmtcnt

optional

integer

The number of identical

placements in this Layout. Refer
Section 8.1 Multiplacement Bid
Requests.

seq

optional

integer

xx (see the layout types). 0 for

the first ad, 1 for the second ad,
and so on. This is not the
sequence number of the
content in the stream.

assets

required

array of
objects

An array of AssetObjects. Any

bid must comply with the array
of elements expressed by the
Exchange.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

4.2 AssetObject
The main container object for each asset requested or supported by Exchange on behalf of
the rendering client. Any object that is required is to be flagged as such. Only one of the
{title,,img,video,data} objects should be present in each object. All others should be
null/absent. The id is to be unique within the AssetObject array so that the response can be
aligned.
Field

Scope

Type

id

required

int

Unique asset ID, assigned by

exchange. Typically a counter
for the array.

req

optional

int

Set to 1 if asset is required

(exchange will not accept a bid
without it)

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Default

Description

Page 11

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

title

optional1

object

Title object for title assets. See

TitleObject definition.

img

optional1

object

Image object for image assets.

See ImageObject definition.

video

optional1

object

Video object for video assets.

See the Video request object
definition. Note that in-stream
video ads are not part of Native.
Native ads may contain a video
as the ad creative itself.

data

optional1

object

Data object for ratings, prices

etc. See DataObject definition.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

: asset object may contain only one of title, img, data or video.

4.3 Title Object

The Title object is to be used for title element of the Native ad.
Field

Scope

Type

Default

Description

len

required

integer

Maximum length of the text in

the title element.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

4.4 Image Object

The Image object to be used for all image elements of the Native ad such as Icons, Main
Image, etc.
Field

Scope

Type

type

optional

integer

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Default
-

Description
Type ID of the image element
supported by the publisher. The
publisher can display this

Page 12

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

information in an appropriate
format. See Table Image Asset
Types for commonly used
examples..
w

optional

integer

Width of the image in pixels.

wmin

recommended

integer

The minimum requested width

of the image in pixels. This
option should be used for any
rescaling of images by the
client. Either w or wmin should
be transmitted. If only w is
included, it should be
considered an exact
requirement.

optional

integer

Height of the image in pixels.

hmin

recommended

integer

The minimum requested height

of the image in pixels. This
option should be used for any
rescaling of images by the
client. Either h or hmin should
be transmitted. If only h is
included, it should be
considered an exact
requirement.

mime

optional

array of
strings

All
types
allowed

Whitelist of content MIME

types supported. Popular MIME
types include, but are not
limited to image/jpg
image/gif.
Each implementing Exchange
should have their own list of
supported types in the
integration docs. See
Wikipedia's MIME page for
more information and links to
all IETF RFCs.
If blank, assume all types are
allowed.

ext

optional

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the

Page 13

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

standard defined in this

specification

4.5 Video Object

The video object to be used for all video elements supported in the Native Ad. This
corresponds to the Video object of OpenRTB 2.3. Exchange implementors can impose their
own specific restrictions. Here are the required attributes of the Video Object. For optional
attributes please refer to OpenRTB 2.3.
Field

Scope

Type

Default

mimes

required

array

Content MIME types supported.

of

Popular MIME types include,but

are not limited to
video/x-ms-wmv for Windows
Media, and video/x-flv for
Flash Video.

string

Description

minduration

required

integer

Minimum video ad duration in

seconds.

maxduration

required

integer

Maximum video ad duration in

seconds.

protocols

required

array of
integers

An array of video protocols the

publisher can accept in the bid
response. See OpenRTB 2.3
Table 6.7 Video Bid Response
Protocols for a list of possible
values.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

4.6 Data Object

The Data Object is to be used for all non-core elements of the native unit such as Ratings,
Review Count, Stars, Download count, descriptions etc. It is also generic for future of Native
elements not contemplated at the time of the writing of this document.
Field

Scope

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Type

Default

Description

Page 14

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

type

required

integer

Type ID of the element

supported by the publisher. The
publisher can display this
information in an appropriate
format. See Table Data Asset
Types for commonly used
examples.

len

optional

integer

Maximum length of the text in

the elements response.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

5 Native Ad Bid Response Markup

The structure and contents of the Bid Response is the same as in the OpenRTB standard. The
difference is how ad creative is returned. The native creative is returned as a JSON-encoded
string in the adm field of the Bid Object, or in response to calling the URL given in the nurl field
of the Bid Object.

5.1 Native Ad Creative JSON

The JSON returned in adm or in response to nurl is a JSON string with the following attributes:
Field

Scope

Type

Default

native

required

object

Description
Top level Native object

5.2 Native Object

The native object is the top level JSON object which identifies an native response. The native
object has following attributes

Field

Scope

Type

ver

optional

integer

Version of the Native Markup

version in use.

assets

required

array of
objects

List of native ads assets.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Default

Description

Page 15

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

link

required

object

Destination Link. See LinkObject

Definition

imptracker[]

optional

array of
strings

Array of impression tracking

URLs, expected to return a 1x1
image or 204 response typically only passed when
using 3rd party trackers.

jstracker

optional

string

Optional javascript impression

tracker. Contains <script> tags
to be executed at impression
time where it can be supported

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

5.3 Asset Object

Corresponds to the Asset Object in the request. The main container object for each asset
requested or supported by Exchange on behalf of the rendering client. Any object that is
required is to be flagged as such. Only one of the {title,img,video,data} objects should be
present in each object. All others should be null/absent. The id is to be unique within the
AssetObject array so that the response can be aligned.
Field

Scope

Type

id

required

int

Unique asset ID, assigned by

exchange, must match one of
the asset IDs in request

req

optional

int

Set to 1 if asset is required.

(bidder requires it to be
displayed).

title

optional1

object

Title object for title assets. See

TitleObject definition.

img

optional1

object

Image object for image assets.

See ImageObject definition.

video

optional1

object

Video object for video assets.

See Video response object
definition. Note that in-stream
video ads are not part of Native.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Default

Description

Page 16

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

Native ads may contain a video

as the ad creative itself.
data

optional1

object

Data object for ratings, prices

etc.

link

optional

object

Link object for call to actions.

This link is to associated to the
other populated field within the
object.

ext2

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

: asset object may contain only one of title, img, data or video.

: Bidders are encouraged not to use asset.ext for exchanging text assets. Use data.ext with
custom type instead.

5.4 Title Object

Corresponds to the Title Object in the request, with the value filled in.
Field

Scope

Type

Default

Description

text

required

String

The text associated with the

text element.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

5.5 Image Object

Corresponds to the Image Object in the request. The Image object to be used for all image
elements of the Native ad such as Icons, Main Image, etc.
Field

Scope

Type

Default

url

required

string

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Description
URL of the image asset.

Page 17

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

recommended

integer

recommended

integer

ext

optional

object

RTB Project

Width of the image in pixels.

Height of the image in pixels.

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

5.6 Data Object

Corresponds to the Data Object in the request, with the value filled in. The Data Object is to
be used for all miscellaneous elements of the native unit such as Ratings, Review Count, Stars,
Downloads, Price count etc. It is also generic for future of Native elements not contemplated
at the time of the writing of this document.
Field

Scope

Type

Default

Description

label

optional

string

The optional formatted string

name of the data type to be
displayed.

value

required

string

The formatted string of data to

be displayed. Can contain a
formatted value such as 5
stars or $10 or 3.4 stars out
of 5.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

5.7 Video Object

Corresponds to the Video Object in the request, yet containing a value of a conforming VAST
tag as a value.
Field

Scope

Type

Default

vasttag

required

string

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Description
vast xml.

Page 18

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

5.8 Link Object

Used for call to action assets, or other links from the Native ad. This Object should be
associated to its peer object in the parent Asset Object. When that peer object is activated
(clicked) the action should take the user to the location of the link.
Field

Scope

Type

Default

Description

url

required

string

Landing URL of the clickable

link.

clktrck[]

optional

array of
strings

List of third-party tracker URLs

to be fired on click of the URL.

fallback

optional

string
(URL)

Fallback URL for deeplink. To be

used if the URL given in url is
not supported by the device.

ext

optional

object

This object is a placeholder that

may contain custom JSON
agreed to by the parties to
support flexibility beyond the
standard defined in this
specification

6 Bid Request/Response Samples

6.1 App Wall Example

Theadmightlooklike

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 19

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

Bid Request

{
"native":{
"assets":[
{
"id":1,
"req":1,
"title":{
"len":30
}
},
{
"id":2,
"req":0,
"data":{
"type":3,
"len":5
}
},
{
"id":3,
"req":1,
"img":{
"type":1,
"w":64,

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 20

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

"h":64,
"mime":[
"image/png"
]
}
},
{
"id":4,
"req":0,
"data":{
"type":2,
"len":10
}
}
]
}
}

Bid Response

{
"native":{
"ver":1,
"link":{
"url":"http://i.am.a/URL",
"fallback":"deeplink://deeplink/url/into/app",
"clktrck":[
"http://a.com/a",
"http://b.com/b"
]
},
"imptracker":[
"http://a.com/a",
"http://b.com/b"
],
"assets":[
{
"id":1,
"title":{
"text":"InstallBOA"
},
"link":{
"url":"http://i.am.a/URL"
}
},
{

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 21

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

"id":2,
"data":{
"value":5
}
},
{
"id":3,
"img":{
"url":"http://cdn.mobad.com/ad.png",
"w":64,
"h":64
}
},
{
"id":4,
"data":{
"value":"Install"
},
"link":{
"url":"http://i.am.a/URL"
}
}
]
}
}

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 22

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

6.2 Chat List Example

Bid Request

{
"native":{
"layout":4,
"assets":[
{
"id":1,
"req":1,
"title":{
"len":30
}
},
{
"id":2,
"req":0,
"data":{
"type":2,
"len":100

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 23

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

}
},
{
"id":3,
"req":1,
"img":{
"type":1,
"w":64,
"h":64,
"mime":[
"image/png"
]
}
}
]
}
}

Bid Response

{
"native":{
"ver":1,
"link":{
"url":"http://i.am.a/URL",
"fallback":"deeplink://deeplink/url/into/app",
"clktrck":[
"http://a.com/a",
"http://b.com/b"
]
},
"imptracker":[
"http://a.com/a",
"http://b.com/b"
],
"assets":[
{
"id":1,
"title":{
"text":"InstallBOA"
}
},
{
"id":2,
"data":{
"value":"ManageFinancesonyourphone"

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 24

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

}
},
{
"id":3,
"img":{
"url":"http://cdn.mobad.com/ad.png",
"w":64,
"h":64
}
}
]
}
}

6.3 Content Stream with Video Element Example

Bid Request

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 25

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

"native":{
"layout":6,
"assets":[
{
"id":1,
"req":1,
"title":{
"len":30
}
},
{
"id":2,
"req":0,
"data":{
"type":3,
"len":10
}
},
{
"id":3,
"req":1,
"type":1,
"img":{
"w":64,
"h":64,
"mime":[
"image/png"
]
}
},
{
"id":4,
"video":{
"linearity":1,
"minduration":15,
"maxduration":30,
"protocols":[
"VAST2.0"
]
}
},
{
"id":5,
"req":0,
"data":{
"type":2,
"len":10
}
}
]

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 26

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

}
}

Bid Response
{
"native":{
"ver":1,
"link":{
"url":"http://i.am.a/URL",
"fallback":"deeplink://deeplink/url/into/app",
"clktrck":[
"http://a.com/a",
"http://b.com/b"
]
},
"assets":[
{
"id":1,
"title":{
"text":"InstallBOA"
}
},
{
"id":2,
"data":{
"value":5
}
},
{
"id":3,
"img":{
"url":"http://cdn.mobad.com/ad.png",
"w":1200,
"h":627
}
},
{
"id":4,
"video":{
"vasttag":"<VASTversion=2.0></VAST>"
}
},
{
"id":5,
"data":{

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 27

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

"value":"Click"
},
"link":{
"url":"http://i.am.a/URL"
}
}
]
}
}

6.4 Google Text Ad

AnGoogletextadwithtitle,description1,description2anddisplayurlcanbe
representedas

Bid Request
{
"native":{
"assets":[
{
"id":1,
"title":{
"len":25
}
},
{
"id":2,
"data":{
"type":2,
"len":35
}
},
{
"id":3,
"data":{
"type":10,
"len":35
}

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 28

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

},
{
"id":4,
"data":{
"type":11,
"len":35
}
}
]
}
}

Bid Response
{
"native":{
"ver":1,
"link":{
"url":"http://i.am.a/URL",
"fallback":"deeplink://deeplink/url/into/app",
"clktrck":[
"http://a.com/a",
"http://b.com/b"
]
},
"assets":[
{
"id":1,
"title":{
"text":"PlasmaTelevision"
}
},
{
"id":2,
"data":{
"value":"Hugerangeofequipmentonsale"
}
},
{
"id":3,
"data":{
"value":"Freedelivery.Ordernow."
}
},
{
"id":4,
"data":{
"value":"mybestplasmatvstore.com"
}

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 29

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

}
]
}
}

7 Reference Lists/Enumerations
7.1 Native Layout IDs
Below is a list of the core layouts described in the introduction above.
An implementing exchange may not support all asset variants or introduce new ones
unique to that system.

Layout ID

Description

Content Wall

App Wall

News Feed

Chat List

Carousel

Content Stream

Grid adjoining the content

500+

Reserved for Exchange specific layouts.

7.2 Native Ad Unit IDs

Below is a list of the core ad unit ids described by IAB here

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 30

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

http://www.iab.net/media/file/IABNativeAdvertisingPlaybook120413.pdf
In feed unit is essentially a layout, it has been removed from the list.
An implementing exchange may not support all asset variants or introduce new ones
unique to that system.

Ad Unit ID

Description

Paid Search Units

Recommendation Widgets

Promoted Listings

In-Ad (IAB Standard) with Native Element Units

Custom /Cant Be Contained

500+

Reserved for Exchange specific formats.

7.3 Data Asset Types

Below is a list of common asset element types of native advertising at the time of
writing this spec. This list is non-exhaustive and intended to be extended by the
buyers and sellers as the format evolves.
An implementing exchange may not support all asset variants or introduce new ones
unique to that system.

Type
ID

Name

Description

Format

sponsored

Sponsored By message where response should

contain the brand name of the sponsor.

text

desc

Descriptive text associated with the product or

service being advertised.

text

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 31

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

rating

Rating of the product being offered to the user.

For example an apps rating in an app store from
0-5.

number
formatted as
string

likes

Number of social ratings or likes of the product

being offered to the user.

number
formatted as
string

downloads

Number downloads/installs of this product

number
formatted as
string

price

Price for product / app / in-app purchase. Value

should include currency symbol in localised
format.

number
formatted as
string

saleprice

Sale price that can be used together with price to

indicate a discounted price compared to a
regular price. Value should include currency
symbol in localised format.

number
formatted as
string

phone

Phone number

formatted
string

address

Address

text

10

desc2

Additional descriptive text associated with the

product or service being advertised

text

11

displayurl

Display URL for the text ad

text

12

ctatext

CTA description - descriptive text describing a

call to action button for the destination URL.

text

500+

XXX

Reserved for Exchange specific usage numbered

above 500

Unknown

7.4 Image Asset Types

Below is a list of common image asset element types of native advertising at the time
of writing this spec. This list is non-exhaustive and intended to be extended by the
buyers and sellers as the format evolves.

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 32

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

An implementing exchange may not support all asset variants or introduce new ones
unique to that system.

Type
ID

Name

Description

Icon

Icon image

Logo

Logo image for the brand/app.

Main

Large image preview for the ad

500+

XXX

Reserved for Exchange specific usage

numbered above 500

8 Implementation Notes
8.1 Multi Placement Bid Requests
If the bid request has a placement count (plcmtcnt) greater than 1, then the implication is
that the bidder is submitting bids to a Generalized Second Price auction where multiple
identical placements are being offered in the same content feed or stream.
Example If a bid request is for 5 ad placements within a feed based layout. The bidder can
return 1-5 bids. The exchange runs a generalized second price auction across these bids. The
bidder can potentially win between 0-5 placements in the auction.
An example bid response would look like
{
"id":"1234567890",
"seatbid":[{
"bid":[{
"id":"1",
"impid":"1",
"price":10,
"nurl":"http://adserver.com/WinNoticeUrlThatReturnsNative1",
"adm":"<nativeresponse>"
},

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 33

OpenRTB Native Ads API Specification Draft Version 0.99.11.13

RTB Project

"bid":[{
"id":"2",
"impid":"1",
"price":20,
"nurl":"http://adserver.com/WinNoticeUrlThatReturnsNative2"
"adm":"<nativeresponse>"
}]
}]
}

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Page 34