In-Feed OpenRTB Introduction

Overview

Sharethrough’s specification for In-Feed OpenRTB has been built using the IAB OpenRTB 2.3 specification, which has added support for native (via the separate native spec) as a subordinate under impression object. Sharethrough does not deviate from OpenRTB 2.3, and this guide serves as a reference for our interpretation, usage, and support of the 2.3 features.

Sharethrough Inventory

Types of Publishers

Unrivaled Scale. Guaranteed Quality.

The Sharethrough Exchange (STX) is the world’s largest in-feed ad exchange. Reach up to 285 million viewers on premium sites.

We have the most premium site list in the in-feed universe. You can access these publishers via tier-1 channels as defined by the IAB. STX is available for in-app, mobile web, and desktop web inventory.

Ad Unit Options and Functionality

Sharethrough ads appear in-feed, mid-post, and below-the-post on web sites (desktop, tablet, smartphone) and mobile apps for both tablets and smartphones. On smartphone and tablet we support Android and iOS. Our ads match the site’s surrounding content in form and function, meaning that each placement will have a unique layout.

You can see an example of how Sharethrough native ads work for various types of content and on various example publishers via our native ad generator tool. Learn more about in-feed native via a variety of resources located here.  

Types of creatives

Clickout

A clickout creative is rendered with a thumbnail, a headline, and small body of text. When the user clicks on the ad unit they are redirected to a landing page.

Native Video

Like clickout creatives, a video creative is rendered with a thumbnail, a headline, and small body of text. However, the video asset will begin silently playing in place of the thumbnail as the ad unit is scrolled into view. A click will enlarge the unit and play the video with audio.

Bid Request

Sharethrough is a supply source, and these are the objects/parameters supported in the bid request.

Supported Objects

Object Name	Supported	Parameters (NOT Supported)	Parameters (Supported)
Bid Request	Yes	at, tmax, allimps, cur, bcat, badv, regs, ext, user	site, app, device, wseat
Impression	Yes	banner, instl, bidfloorcur, iframebuster	native, bidfloor, secure, pmp, tagid, video
Native	Yes	See below
Private Marketplace	Yes	See below
Banner	No
Video	Yes	protocol, w, h, startdelay, skip, skipmin, skipafter, sequence, battr, linearity, maxextended, minbitrate, maxbitrate, maxbitrate, delivery, pos, , companionad, api, companiontype	mimes, minduration, maxduration, protocols, playbackmethod
Site	Yes	name, sectioncat, pagecat, privacypolicy, ref, search, keywords, ext	id, page, domain, cat, publisher (object), content (object)
App	Yes	domain, sectioncat, pagecat, ver, privacy policy, paid, keywords, storeurl, ext	id, name, cat, bundle, publisher (object), content (object)
Content	Yes	id, episode, title, series, season, producer, url, cat, videoquality, context, contentrating, userrating, qagmediarating, keywords, livestream, sourcerelationship, len, embeddable, ext	language
Device	Yes	didmd5, dpidmd5, macsha1, macmd5, ipv6, flashver, js, connectiontype	ua, geo, make, model, os, osv, devicetype, dnt, language, dpidsha1 (app impressions), ext (app impression)
User	Yes		buyeruid
Publisher	No	All data in site and app objects	id
Producer	No
Geo	Yes in device	regionfips104, region, city, zip, ext, lat, lon	country, metro, type
Data	No
Segment	No
Content	No

Impression Object

Top level object to describe the impression available for auction.

Field Name	Type	Default	Description
id	string		Unique identifier for the impression
bidfloor	float		Minimum bid for the impression expressed in vCPM
secure	integer	0	Indicates whether the placement was served via https. 0 for false, 1 for true.
native	object		Describes data about the native impression available.
pmp	object		Describes any private marketplace deals available
tagid	string		Identifier for specific ad placement that was used to initiate the auction

Video Object

Field Name	Type	Default	Description
mimes	string array		The MIME type of videos. Always will be ["video/mp4"]. Videos submitted to the creative approval endpoint are transcoded to this format.
minduration	integer		Minimum length of the ad, in seconds. Always will be 3 seconds.
maxduration	integer		Maximum length of the ad, in seconds. Always will be 300 seconds, or 5 minutes.
protocols	integer array		Indicates what Video Ad protocols are accepted. Always will be [2, 3, 5, 6, 7, 8] to indicate VAST version 2, 3, 4 and their wrappers. The VAST protocol reflects the protocols accepted by the creative approval endpoint for preprocessing. Once processed, bidder only needs to respond with creative ID.
playbackmethod	integer array		How the video can be rendered. Always will be [2] to indicate “Auto-Play Sound Off”

1. The VAST protocol reflects the protocols accepted by the creative approval endpoint for preprocessing.
2. When a Video object is outside of the Native object, non-Native outstream video is being requested. An additional Video Asset object inside of the Native object means that Native outstream creatives are allowed on this impression. Native outstream includes the other Native assets, such as Title, Description, Advertiser Name, etc.

Native Object

Used to define data about the type of in-feed impression available. This contains a single field of request which will represent a Native Request Object which has been encoded as a string for RTB 2.3 or an object for RTB 2.4.

Field Name	Type	Default	Description
request	string/object		Contains the Native Request Object below encoded as a string for 2.3 or object for 2.4

Native Request Object

Data about the native impression available. This should be encoded as a stringified JSON object in the request above for RTB 2.3. See the sample requests for an example.

Field Name	Type	Default	Description
ver	string	1.0
layout	integer	3	(deprecated - Native 1.0 only) The layout ID of the native ad unit. Always 3 (news feed) for Sharethrough
adunit	integer	3	(deprecated - Native 1.0 only) The ad unit ID of the native ad unit. This corresponds to the 6 native ad unit types defined by the IAB. Will always be 4 (promoted listing) or 2 (recommendation widgets - which in the case of Sharethrough means ads on article/post pages).
plcmtcnt	integer	1	The number of identical placements available on this URL. Always 1.
assets	array		An array of Asset Objects which specifies what Sharethrough expects back with the bid. See below.
plcmttype	integer	3	(Native 1.1 only) The design/format/layout of the ad unit being offered. Always 1 (content centric) for Sharethrough.
context	integer	3	(Native 1.1 only) The context in which the ad appears.
ext	object		Not supported

Asset Object

The main container object for each asset requested by Sharethrough. Only one object will be present in each asset object with a unique id.

Field Name	Type	Default	Description
id	integer		Unique asset id, to be returned with asset responses
required	integer		Set to 1 if required, 0 if optional
title	object		Title object
img	object		Image object
data	object		Data object
video	object		Video object - present for placements supporting video
ext			Not supported

Title Asset Object

Sets the title for the native ad.

Field Name	Type	Default	Description
len	integer	140	Maximum length
ext			Not supported

Image Asset Object

Note the difference between Native 1.0 and 1.1. Note also that the Native 1.1 information below only applies to rtb-tools.sharethrough.com for testing purposes; Currently, adserver still sends Native 1.0-style image assets in bid requests.

Native 1.0

A maximum of three image objects will be requested:

• a small / mobile thumbnail (image type = 1)
• a large / desktop thumbnail (image type = 3)
• a brand logo (image type = 2)

For mobile web and app bid requests, the large thumbnail image is optional and small thumbnail is required. For desktop bid requests, the small thumbnail image is optional and large thumbnail is required. The brand logo image is optional for all bid requests irrespective of the device.

Field Name	Type	Default	Description
type	integer		Type of image being requested - 1,2, or 3
wmin	integer		Minimum width is 600 pixels for type 3, 320 pixels for type 1, and 48 for type 2
hmin	integer		Minimum height is 315 pixels for type 3, 180 pixels for type 1, and 48 for type 2
mime			Will be blank; all standard types allowed. PNG recommended. Animated gif not allowed.
w			Not supported
h			Not supported
ext			Not supported

Native 1.1

A maximum of three image objects will be requested:

• a small / mobile thumbnail (image type = 3)
• a large / desktop thumbnail (image type = 3)
• a brand logo (image type = 1)

Note that mobile and desktop thumbnails share the same image type (3), and hence appropriate sizes should be set for mobile and desktop thumbnails depending on the device type.

For mobile web and app bid requests, the large thumbnail image is optional and small thumbnail is required. For desktop bid requests, the small thumbnail image is optional and large thumbnail is required. The brand logo image is optional for all bid requests irrespective of the device.

Field Name	Type	Default	Description
type	integer		Type of image being requested - 1 or 3
wmin	integer		Minimum width is 600 pixels for type 3 and 320 pixels for type 1
hmin	integer		Minimum height is 315 pixels for type 3 and 180 pixels for type 1
mime			Will be blank; all standard types allowed. PNG recommended. Animated gif not allowed.
w			Not supported
h			Not supported
ext			Not supported

Video Asset Object

This object describes a video asset to be played in the unit.

Field Name	Type	Default	Description
mimes	string array		The MIME type of videos. Always will be ["video/mp4"]. Videos submitted to the creative approval endpoint are transcoded to this format.
minduration	integer		Minimum length of the ad, in seconds. Always will be 3 seconds.
maxduration	integer		Maximum length of the ad, in seconds. Always will be 300 seconds, or 5 minutes.
protocols	integer array		Indicates what Video Ad protocols are accepted. Always will be [2, 3, 5, 6, 7, 8] to indicate VAST version 2, 3, 4 and their wrappers. The VAST protocol reflects the protocols accepted by the creative approval endpoint for preprocessing. Once processed, bidder only needs to respond with creative ID.

Data Asset Object

The data object provides for additional non-standard fields, some of which are used by Sharethrough.

Field Name	Type	Default	Description
type	integer		Specifies the type of data being requested. See table Data Asset Types for values
len	integer		Maximum length
ext			Not supported

Site Object

The site object describes the site where the impression will be shown.

Field Name	Type	Default	Description
id	string		Exchange specific unique identifier for the site
page	string		URL of the page where the impression will be shown
domain	string		Domain of the site
cat	string		IAB categories for the site
publisher	object		See below
content	object		See below
ext			Not supported

App Object

The app object describes the app where the impression will be shown for in-app requests.

Field Name	Type	Default	Description
id	string		Exchange specific unique identifier for the app
name	string		Name of the app
bundle	string		Bundle identifier of the app
cat	string		IAB categories for the site
publisher	object		See below
content	object		See below
ext			Not supported

Publisher Object

The publisher object describes the publisher of the site or app where the impression will be shown.

Field Name	Type	Default	Description
id	string		Exchange specific unique identifier for the publisher
ext			Not supported

Content Object

The content object describes the publisher of the site or app where the impression will be shown.

Field Name	Type	Default	Description
language	string		Content language using ISO-639-1-alpha-2

Device Object

The device object describes the device where the impression will be shown.

Field Name	Type	Default	Description
geo	object		Location of the device
ip	string		IPv4 address closest to the device
ua	string		Browser user agent string
dnt	integer		Do Not Track: 0 - Unrestricted, 1 - Tracking must be limited
js	integer		JavaScript support: 0 - No, 1 - Yes
make	string		Device make
model	string		Device model
os	string		Operating system name
osv	string		Operating system version
connectiontype	integer		Network connection type
devicetype	integer		General type of the device
ifa	string		Device advertising identifier (in-app only)
ext			Not supported

Geo Object

The geo object contains information about the location of the device.

Field Name	Type	Default	Description
country	string		Country code using ISO-3166-1-alpha-2
metro	string		DMA code for US locations
type	string		Source of location data. Always 2 for Sharethrough.
ext			Not supported

User Object

The user object contains information known about the user.

Field Name	Type	Default	Description
buyeruid	string		Buyer specific ID of the user as mapped by STX.
ext			Not supported

Private Marketplace Object

This object describes the private marketplace of deals between buyers and sellers.

Field Name	Type	Default	Description
private_auction	integer		A flag indicating that this impression is a private auction eligible only to seats named in the deal object.
deals	object array		Set of ‘deal’ objects of direct deals eligible for this impression.

Deal Object

This object describes the private marketplace of deals between buyers and sellers.

Field Name	Type	Default	Description
id	string		Unique identifier for deal
bidfloor	float		Bid floor for this impression
wseat	string array		Set of seat id’s allowed to bid on this deal

System Defaults

tmax - Maximum time in ms to submit a bid is 120 ms

Bid Response

Summary

Sharethrough supports a subset of the OpenRTB Spec, the details of which are listed under Supported Objects.

One of the largest distinctions between native bids and other bid types is that the native response is composed of discrete assets which are then recombined on the client to form the ad unit in a a manner which is consistent with the ad placement. All assets are defined by general categories – title, img, data, video – and further refined by type IDs. The mapping of currently supported assets are included in the Reference Lists section.

Supported Objects

Object Name	Parameters (NOT Supported)	Parameters (Supported)
Bid Response Object	cur, customdata, ext	id, bdid, seatbid
Seat Bid	group, ext	bid, seat
Bid	adid, iurl, attr	adm, id, impid, price, nurl, adomain, cid, crid, dealid, ext

Seat Bid Object

The seat bid object contains a collection of bids by seat

Field	Scope	Type	Description
bid	required	object array	array of bid objects (see below)
seat	required	string	ID of the seat for which the bids belong to

Bid Object

The bid object contains a list of bids for the impression.

Field	Scope	Type	Description
id	required	string	unique identifier for the bid
impid	required	string	ID of impression for which the bid is bidding on
price	required	float	bid price in vCPM
adomain	required	string array	advertiser domain
crid	required	string	creative identifier
adm	required	see below	native ad markup for the bid. See below for more details
cid	optional	string	campaign identifier for the creative
nurl	optional	string	notification url to use for notifying bidders when their bid has won and become visible
dealid	optional	string	reference to a deal ID from the impression

The price field is the dollar vCPM which the DSP bids with. Only two decimals would be accepted in the ‘price’ field and anything beyond will be truncated.

Native Object

The adm object should be populated with a string escaped JSON for the native response object as shown in the bid response example. The native object has the below fields.

Field	Scope	Type	Description
assets	See notes	object array	List of native ad’s assets
link	required	object	Link object for destination URL
imptrackers	optional	string array	Array of impression tracking URLs, expected to return a 1x1 image or 204 response. Called for visible impressions only.
jstracker	optional	string	A valid HTML, Javascript is already wrapped in <script> tags. It will be executed at impression time. Note that the value of src attribute in the <script> tag needs to be well formed with quotes as shown in the sample bid response.
ext			Not supported

Asset Object

Corresponds to the Asset Object in the request. The main container object for each asset requested or supported. Only one of the {title, image, data} objects should be present in each object.

Field	Scope	Type	Description
id	required	integer	Unique asset id, assigned in bid request - must match the request
required	optional	integer	Set to 1 if asset is required by the bidder to be used/shown
title	optional	object	Title object for title assets
img	optional	object	Image object for image assets
data	optional	object	Data object for data assets
video	optional	object	Data object for video assets
link			Not supported (use top level link object)
ext			Not supported

Title Object

Sets the title for the native ad.

Field	Scope	Type	Description
text	required	string	Text for title
ext			Not supported

Image Object

Three image Objects will be requested - a thumbnail image large and small, which is required, and a brand logo image, which is optional

Field	Scope	Type	Description
url	required	string	URL for the image asset
w			Not supported
h			Not supported
ext			Not supported

Data Object

The data object provides for additional non-standard fields, some of which are used by Sharethrough.

Field	Scope	Type	Description
value	required	string	Value to display for this element
label			Not supported
ext			Not supported

Link Object

The link object populated provides for the destination URL and tracker URLs which need to be fired in the event of a click-out. This object should be associated as the master link in the top level Native Ad response object. Sharethrough does not support link objects in the individual assets yet.

Field	Scope	Type	Description
url	required	string	Landing URL of the clickable link
clicktrackers	optional	string array	Array of click tracking URLs, expected to return a 1x1 image or 204 response.
fallback			Not supported
ext			Not supported

Video Object

The video object provides for VAST XML markup.

Field	Scope	Type	Description
vasttag	required	string	String escaped VAST XML tag
ext			Not supported

Bid Response Validator

We have built a bid response validator which will help debug JSON issues in the bid response.

Win Notification

The win notification URL will only be called after the auction is won and the ad unit became visible by IAB standards (50% of pixels in view for 1 second). The win notification URL and its format are defined by the bidder. A number of substitution macros can be inserted into the win notice URL definition. Prior to calling a win notice URL, STX will search the specified URL for any of the defined macros and replace them with the appropriate data.

By default Sharethrough will notify you when you won the auction and the ad became visible (and thus billable). This will be indicated in the visible status via the auction_visible substitution macro.

Note that the substitution is simple in the sense that wherever a legal macro is found, it will be replaced without regard for syntax correctness. Furthermore, if the source value is an optional parameter that was not specified, the macro will simply be removed (i.e., replaced with a zero-length string).

String	Meaning
${AUCTION_AD_ID}	ID of a preloaded ad to be served if the bid wins. Note that this will always be replaced with an empty string "".
${AUCTION_ID}	ID of the bid request; from “id” attribute.
${AUCTION_BID_ID}	ID of the bid; from “bidid” attribute.
${AUCTION_IMP_ID}	ID of the impression just won; from “impid” attribute.
${AUCTION_SEAT_ID}	ID of the bidder’s seat for whom the bid was made.
${AUCTION_PRICE}	Settlement price using the same currency and units as the bid.
${AUCTION_CURRENCY}	The currency used in the bid (explicit or implied); for confirmation only.

Creative Approval Service

Creative Submission

Creatives must be approved in advance before they will be allowed to be served in the auction. Creatives are reviewed manually so time should be allowed for the creative approval to occur. Each submission must have a unique creative ID. The bid response at time of auction must contain a crid field which matches this creative ID and assets matching the assets on the approved submission.

The API provides for submitting a creative for verification and receiving a post-back with the approval status. You can submit a new creative to the STX verification pipeline by sending an HTTP POST request to the creative approval service at:

[URL to be provided during integration]

You may resubmit any creative which failed to be approved by modifying it and submitting with a new creative ID.

Additionally, you may update the contents of an existing creative by PUTting (instead of POSTing) to /creatives endpoint with the same creative ID. Note that a creative won’t be served after such an update, pending a new approval.

Native 1.0 Clickout Creative

Native 1.0 clickout creative submission example:

POST|PUT http://stx.sharethrough.com/creatives
Authorization: /* auth token here */ (e.g "Token token=#{seat_api_key}")
Content-Type: application/json

{
  "crid": "DEF123",
  "adm": {
    "clk": "http://www.mycontentsite.com/page.htm",
    "assets": [
      { "title": { "text": "Learn about this awesome thing" } },
      { "img": { "url": "http://www.example.com/thumbnail1.png", "type": 1 } },
      { "img": { "url": "http://www.example.com/brandlogo1.png", "type": 2 } },
      { "img": { "url": "http://www.example.com/largethumb1.png", "type": 3 } },
      { "data": { "value": "My Brand" }, "type": 1 },
      { "data": { "value": "Learn all about this awesome story of someone using my product." }, "type": 2 }
    ]
  }
}

The submission of this type mimics a simplified form of the RTB native 1.0 bid response JSON.

Field	Required	Description
title	Yes	Title or headline of the creative.
img, type 1	No*	Thumbnail used for mobile / small form-factor devices. *If not provided, then a desktop thumbnail must be present
img, type 2	No	Icon for the creatives brand, displayed next to the brand name.
img, type 3	No*	Thumbnail used for desktop / large form-factor devices. *If not provided, then a desktop thumbnail must be present
data, type 1	Yes	The name of the brand of the creative
data, type 2	Yes	The description or main copy of the native unit.

Native 1.1 Clickout Creative

Native 1.1 clickout creative submission example:

POST|PUT http://stx.sharethrough.com/creatives
Authorization: /* auth token here */ (e.g "Token token=#{seat_api_key}")
Content-Type: application/json

{
  "crid": "DEF123",
  "adm": {
    "clk": "http://www.mycontentsite.com/page.htm",
    "assets": [
      { "title": { "text": "Learn about this awesome thing" } },
      { "img": { "url": "http://www.example.com/brandlogo1.png", "type": 1 } },
      { "img": { "url": "http://www.example.com/thumbnail1.png", "type": 3 } },
      { "data": { "value": "My Brand" }, "type": 1 },
      { "data": { "value": "Learn all about this awesome story of someone using my product." }, "type": 2 }
    ]
  }
}

The submission of this type mimics a simplified form of the RTB native 1.1 bid response JSON.

Field	Required	Description
title	Yes	Title or headline of the creative.
img, type 1	No	Icon for the creatives brand, displayed next to the brand name.
img, type 3	Yes	Thumbnail used for mobile / small form-factor, or desktop / large form-factor devices.
data, type 1	Yes	The name of the brand of the creative
data, type 2	Yes	The description or main copy of the native unit.

VAST support

Vast van be submitted similarly to a clickout as above, but with the included video tag:

VAST submission example:

POST|PUT http://stx.sharethrough.com/creatives
Authorization: /* auth token here */ (e.g "Token token=#{seat_api_key}")
Content-Type: application/json

{
  "crid": "DEF123",
  "adm": {
    "clk": "http://www.mycontentsite.com/page.htm",
    "assets": [
      { "title": { "text": "Learn about this awesome thing" } },
      { "img": { "url": "http://www.example.com/thumbnail1.png", "type": 1 } },
      { "img": { "url": "http://www.example.com/brandlogo1.png", "type": 2 } },
      { "img": { "url": "http://www.example.com/largethumb1.png", "type": 3 } },
      { "data": { "value": "My Brand" }, "type": 1 },
      { "data": { "value": "Learn all about this awesome story of someone using my product." }, "type": 2 },
      { "video": { "vasttag": "[string escaped vast XML" } }
    ]
  }
}

Sample VAST XML:

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="2.0">
  <Ad>
    <InLine>
      <AdSystem version="1.0">Sharethrough</AdSystem>
      <AdTitle><![CDATA[Learn about this awesome thing]]></AdTitle>
      <Description><![CDATA[Learn all about this awesome story of someone using my product.]]></Description>
      <Advertiser><![CDATA[My Brand]]></Advertiser>
      <Impression><![CDATA[http://example.com/impression.gif]]></Impression>
      <Creatives>
        <Creative sequence="1" id="unique-creative-id">
          <Linear>
            <MediaFiles>
              <MediaFile type="video/mp4"><![CDATA[http://example.com/video-ad.mp4]]></MediaFile>
            </MediaFiles>
            <TrackingEvents>
              <TrackingEvent event="start"><![CDATA[http://example.com/playback-start.gif]]></TrackingEvent>
              <TrackingEvent event="progress" offset="00:00:03"><![CDATA[http://example.com/3-second-view.gif]]></TrackingEvent>
              <TrackingEvent event="progress" offset="00:00:10"><![CDATA[http://example.com/10-second-view.gif]]></TrackingEvent>
              <TrackingEvent event="progress" offset="00:00:15"><![CDATA[http://example.com/15-second-view.gif]]></TrackingEvent>
              <TrackingEvent event="progress" offset="00:00:30"><![CDATA[http://example.com/30-second-view.gif]]></TrackingEvent>
              <TrackingEvent event="complete"><![CDATA[http://example.com/playback-complete.gif]]></TrackingEvent>
            </TrackingEvents>
            <VideoClicks>
              <ClickTracking><![CDATA[http://example.com/video-click.gif]]></ClickTracking>
            </VideoClicks>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Video creatives can be submitted for approval using VAST versions 2, 3 ,or 4.

Event details

The following events are supported:

Event	Notes
<Impression>	All Sharethrough RTB video creatives are Auto-Play Sound Off, so this will always fire just slightly before the <TrackingEvent event="start"> beacon, assuming the media file is playable.
<TrackingEvent event=“start”>	All Sharethrough RTB video creatives are Auto-Play Sound Off, so this will always fire slightly after the <Impression> beacon.
<TrackingEvent event=“progress” offset=“…”>	Only supports the following values for offset: 00:00:03 00:00:10 00:00:15 00:00:30
<TrackingEvent event=“complete”>
<ClickTracking/>	This will be fired for any engagement with the video player.

Creative Status

We will call back to the creative approval endpoint when your creative has been approved or rejected as follows:

Creative status message example

{
  "status": 0,
  "crid": "DEF123",
  "seat": "ABC1234",
  "expiry": "2015-12-31"
}

All the status message descriptions are available in the Approval Responses table.

Reference Lists

Feed Item Type

Value	Description
1	Collapsed Item (Include Image) - collapsed feed items are typically found in feed pages, to match the surrounding feed items. On initial click, these ads will click-through if they are click-out ads, and will expand to show the content if they have an video or other unique creatives (when supported in the future).
2	Pre-Expanded Item (Includede Image) - sometimes included in feed pages, and more often included in post pages. These units clickout on first click for clickout creatives, and are already expanded so simply engage with the media directly in the case of video or other unique creatives (when supported in the future).

Data Asset Types

Value	Description
1	Sponsored-by message, for example to be displayed as ‘Promoted by Brand’ in the unit. Only send the ‘Brand’ part - the ‘Promoted by’ part will be added automatically. Required.
2	Description - shown in some units depending on the size and design. It will be shown if available and not shown otherwise; this info is not available in the bid request and the required parameter cannot be respected. Required.
501	Opt-Out Text - Optional text that can be shown for DSPs with specific opt-out requirements. Please reach out to your integration team for more info.
502	Opt-Out URL - Optional url that can be displayed for DSPs with specific opt-out requirements. Please reach out to your integration team for more info.

Image Asset Types

Value	Description
1	Brand logo image for Native 1.1
2	Brand logo image for Native 1.0 (deprecated)
3	Thumbnail image to show

Approval Responses

Value	Description
0	Approved
1	Rejected - Inappropriate Content
2	Rejected - Content quality
3	Rejected - Inaccurate title/description
4	Rejected - Landing page quality
5	Reject - other

Multiple JS Trackers

Accepted Format

A string containing the tracker URL wrapped with a script tag
ex: <script src="http://cdn.doubleverify.com/tracker1"></script>

There is a max of 2 trackers are allowed, please concatenate the trackers together
ex: <script src="http://z.moatads.com/tracker1"></script><script src="http://z.moatads.com/tracker2"></script>

jstrackers: "<script src="http://z.moatads.com/tracker1"></script><script src="http://z.moatads.com/tracker2"></script>"

The bid will be rejected if

1. More than 2 trackers are sent

2. Either of the 2 trackers is not from a whitelisted domain

3. Trackers contain other tags
   ex: <script src="http://cdn.doubleverify.com/tracker"></script><noscript></noscript>

Request/Response Samples

Bid Request Samples

This section includes sample bid request JSON’s for mobile web, mobile app and desktop web.

The native.request object is a JSON that is string escaped.

Mobile Web

{
  "site": {
    "domain": "example.com",
    "page": "http://example.com/10-things-that-prove-native-advertising-works",
    "id": "197c9930",
    "publisher": {
      "id": "deadb33f"
    },
    "content": {
      "language": "en"
    },
    "cat": [
      "IAB1",
      "IAB14",
      "IAB18"
    ]
  },
  "id": "94d8a111-c232-4b38-a4ac-f6aa213e4a80",
  "imp": [
    {
      "tagid": "197c9930",
      "native": {
        "request": "{\"native\":{\"plcmtcnt\":1,\"assets\":[{\"id\":3,\"required\":0,\"img\":{\"hmin\":48,\"wmin\":48,\"type\":2}},{\"id\":11,\"required\":0,\"data\":{\"len\":2000,\"type\":501}},{\"id\":12,\"required\":0,\"data\":{\"len\":2000,\"type\":502}},{\"id\":4,\"required\":0,\"img\":{\"hmin\":315,\"wmin\":600,\"type\":3}},{\"id\":1,\"required\":1,\"title\":{\"len\":200}},{\"id\":5,\"required\":1,\"data\":{\"len\":140,\"type\":1}},{\"id\":6,\"required\":1,\"data\":{\"len\":200,\"type\":2}},{\"id\":2,\"required\":1,\"img\":{\"hmin\":48,\"wmin\":48,\"type\":1}}],\"adunit\":2,\"ver\":\"1.0\",\"layout\":3}}",
        "adunit": 2,
        "ver": "1.0",
        "layout": 3
      },
      "id": "1",
      "bidfloor": 3.5,
      "secure": 0
    }
  ],
  "user": {
    "buyeruid": "1760802103"
  },
  "device": {
    "connectiontype": 2,
    "devicetype": 4,
    "ip": "24.0.0.254",
    "model": "iPod Touch",
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12H143 Safari/600.1.4",
    "geo": {
      "country": "US",
      "metro": "508",
      "type": 2
    },
    "os": "iOS",
    "osv": "8",
    "language": "en",
    "make": "Apple",
    "js": 1,
    "dnt": 0
  }
}

Mobile App

{
  "id": "94d8a111-c232-4b38-a4ac-f6aa213e4a80",
  "app": {
    "name": "com.example.droidapp",
    "bundle": "2.1",
    "id": "51929922",
    "publisher": {
      "id": "deadb33f"
    },
    "content": {
      "language": "en"
    },
    "cat": [
      "IAB1",
      "IAB24"
    ]
  },
  "imp": [
    {
      "tagid": "51929922",
      "native": {
        "request": "{\"native\":{\"plcmtcnt\":1,\"assets\":[{\"id\":3,\"required\":0,\"img\":{\"hmin\":48,\"wmin\":48,\"type\":2}},{\"id\":11,\"required\":0,\"data\":{\"len\":2000,\"type\":501}},{\"id\":12,\"required\":0,\"data\":{\"len\":2000,\"type\":502}},{\"id\":4,\"required\":0,\"img\":{\"hmin\":315,\"wmin\":600,\"type\":3}},{\"id\":1,\"required\":1,\"title\":{\"len\":200}},{\"id\":5,\"required\":1,\"data\":{\"len\":140,\"type\":1}},{\"id\":6,\"required\":1,\"data\":{\"len\":200,\"type\":2}},{\"id\":2,\"required\":1,\"img\":{\"hmin\":48,\"wmin\":48,\"type\":1}}],\"adunit\":2,\"ver\":\"1.0\",\"layout\":3}}",
        "adunit": 2,
        "ver": "1.0",
        "layout": 3
      },
      "id": "1",
      "bidfloor": 3.5,
      "secure": 0
    }
  ],
  "user": {
    "buyeruid": "1760802103"
  },
  "device": {
    "connectiontype": 4,
    "devicetype": 4,
    "ip": "96.0.0.254",
    "model": "One A0001",
    "ua": "Dalvik/2.1.0 (Linux; U; Android 5.0.2; A0001 Build/LRX22G); STR 1.1.1",
    "geo": {
      "country": "US",
      "metro": "501",
      "type": 2
    },
    "os": "Android",
    "osv": "",
    "language": "en",
    "make": "Oneplus",
    "js": 1,
    "dnt": 0
  }
}

Desktop Web

{
  "site": {
    "domain": "example.com",
    "page": "http://www.example.com/sample",
    "id": "53198e3f",
    "publisher": {
      "id": "deadb33f"
    },
    "content": {
      "language": "en"
    },
    "cat": [
      "IAB7",
      "IAB17"
    ]
  },
  "id": "94d8a111-c232-4b38-a4ac-f6aa213e4a80",
  "imp": [
    {
      "tagid": "53198e3f",
      "native": {
        "request": "{\"native\":{\"plcmtcnt\":1,\"assets\":[{\"id\":3,\"required\":0,\"img\":{\"hmin\":48,\"wmin\":48,\"type\":2}},{\"id\":11,\"required\":0,\"data\":{\"len\":2000,\"type\":501}},{\"id\":12,\"required\":0,\"data\":{\"len\":2000,\"type\":502}},{\"id\":2,\"required\":0,\"img\":{\"hmin\":48,\"wmin\":48,\"type\":1}},{\"id\":1,\"required\":1,\"title\":{\"len\":200}},{\"id\":5,\"required\":1,\"data\":{\"len\":140,\"type\":1}},{\"id\":6,\"required\":1,\"data\":{\"len\":200,\"type\":2}},{\"id\":4,\"required\":1,\"img\":{\"hmin\":315,\"wmin\":600,\"type\":3}}],\"adunit\":2,\"ver\":\"1.0\",\"layout\":3}}",
        "adunit": 2,
        "ver": "1.0",
        "layout": 3
      },
      "id": "1",
      "bidfloor": 3.5,
      "secure": 0
    }
  ],
  "user": {
    "buyeruid": "1760802103"
  },
  "device": {
    "connectiontype": 1,
    "devicetype": 2,
    "ip": "162.0.0.254",
    "model": "Unknown",
    "ua": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.130 Safari/537.36",
    "geo": {
      "country": "US",
      "metro": "803",
      "type": 2
    },
    "os": "unknown",
    "osv": "44",
    "language": "en",
    "make": "Unknown",
    "js": 1,
    "dnt": 0
  }
}

Sample Bid Request JSON as per the Native1.1 spec in Open RTB-2.4.

{
  "site": {
    "domain": "example.com",
    "page": "http://www.example.com/sample",
    "id": "53198e3f",
    "publisher": {
      "id": "deadb33f"
    },
    "content": {
      "language": "en"
    },
    "cat": [
      "IAB7",
      "IAB17"
    ]
  },
  "id": "94d8a111-c232-4b38-a4ac-f6aa213e4a80",
  "imp": [
    {
      "tagid": "53198e3f",
      "native": {
        "request": {
          "native": {
            "plcmtcnt": 1,
            "assets": [
              {
                "id": 21,
                "required": 0,
                "img": {
                  "hmin": 48,
                  "wmin": 48,
                  "type": 1
                }
              },
              {
                "id": 11,
                "required": 0,
                "data": {
                  "len": 2000,
                  "type": 501
                }
              },
              {
                "id": 12,
                "required": 0,
                "data": {
                  "len": 2000,
                  "type": 502
                }
              },
              {
                "id": 22,
                "required": 0,
                "img": {
                  "hmin": 48,
                  "wmin": 48,
                  "type": 3
                }
              },
              {
                "id": 1,
                "required": 1,
                "title": {
                  "len": 200
                }
              },
              {
                "id": 5,
                "required": 1,
                "data": {
                  "len": 140,
                  "type": 1
                }
              },
              {
                "id": 6,
                "required": 1,
                "data": {
                  "len": 200,
                  "type": 2
                }
              },
              {
                "id": 23,
                "required": 1,
                "img": {
                  "hmin": 315,
                  "wmin": 600,
                  "type": 3
                }
              }
            ],
            "plcmttype": 1,
            "context": 1,
            "ver": "1.1"
          }
        }
      },
      "id": "1",
      "bidfloor": 3.5,
      "secure": 0
    }
  ],
  "user": {
    "buyeruid": "1760802103"
  },
  "device": {
    "connectiontype": 1,
    "devicetype": 2,
    "ip": "162.0.0.254",
    "model": "Unknown",
    "ua": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.130 Safari/537.36",
    "geo": {
      "country": "US",
      "metro": "803",
      "type": 2
    },
    "os": "unknown",
    "osv": "44",
    "language": "en",
    "make": "Unknown",
    "js": 1,
    "dnt": 0
  }
}

Bid Response Samples

This section includes a sample bid response JSON.

The adm object is a JSON that is string escaped.

{
    "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
    "bidid": "ABC123",
    "seatbid": [
        {
            "seat": "1894",
            "bid": [
                {
                    "id": "ABC123",
                    "impid": "1",
                    "price": 12.25,
                    "nurl": "http://www.myads.com/winnotice.php",
                    "adomain": ["mybrand.com"],
                    "cid": "ABC123",
                    "crid": "DEF123",
                    "adm": " { \"native\": { \"link\": { \"url\": \"http://i.am.a/URL\", \"clicktrackers\": [ \"http://a.com/clk1\", \"http://a.com/clk2\" ] }, \"imptrackers\": [ \"http://a.com/imp1\", \"http://b.com/imp2\" ], \"jstracker\": \"<script src=\\\"http://supported-tracker-domain/mCh7nspyora8hafx6qjs\\\"></script>\", \"assets\": [ { \"id\": 123, \"required\": 1, \"title\": { \"text\": \"Learn about this awesome thing\" } }, { \"id\": 124, \"required\": 1, \"img\": { \"url\": \"http://www.myads.com/thumbnail1.png\" } }, { \"id\": 125, \"required\": 1, \"img\": { \"url\": \"http://www.myads.com/brandlogo1.png\" } }, { \"id\": 128, \"required\": 1, \"img\": { \"url\": \"http://www.myads.com/largethumb1.png\" } }, { \"id\": 126, \"required\": 1, \"data\": { \"value\": \"My Brand\" } }, { \"id\": 127, \"required\": 1, \"data\": { \"value\": \"Learn all about this awesome story of someone using my product.\" } }, { \"id\": 129, \"required\": 0, \"data\": { \"value\": \"Opt-out text.\" } }, { \"id\": 130, \"required\": 0, \"data\": { \"value\": \"Opt-out URL.\" } } ] } }"
                }
            ]
        }
    ]
}

The unescaped adm object is shown here.

{
    "native": {
        "link": {
            "url": "http://i.am.a/URL",
            "clicktrackers": [
                "http://a.com/clk1",
                "http://b.com/clk2"
            ]
        },
        "imptrackers": [
            "http://a.com/imp1",
            "http://b.com/imp2"
        ],
        "jstracker": "<script src=\"http://supported-tracker-domain/mCh7nspyora8hafx6qjs\"></script>",
        "assets": [
            { "id": 123, "required": 1, "title": { "text": "Learn about this awesome thing" } },
            { "id": 124, "required": 1, "img": { "url": "http://www.myads.com/thumbnail1.png" } },
            { "id": 125, "required": 1, "img": { "url": "http://www.myads.com/brandlogo1.png" } },
            { "id": 128, "required": 1, "img": { "url": "http://www.myads.com/largethumb1.png" } },
            { "id": 126, "required": 1, "data": { "value": "My Brand" } },
            { "id": 127, "required": 1, "data": { "value": "Learn all about this awesome story of someone using my product." } },
            { "id": 129, "required": 0, "data": { "value":"Opt-out text." } },
            { "id": 130, "required": 0, "data": { "value":"Opt-out URL." } }
        ]
    }
}

Sample Bid Response JSON as per the Native1.1 spec in Open RTB-2.4.

{
   "id":"80ce30c53c16e6ede735f123ef6e32361bfc7b22",
   "seatbid":[
      {
         "seat":"1894",
         "bid":[
            {
               "id":"ABC123",
               "impid":"1",
               "price":12.25,
               "nurl":"http://www.myads.com/winnotice.php",
               "adomain": ["mybrand.com"],
               "cid":"ABC123",
               "crid":"DEF123",
               "adm":{
                  "native":{
                     "link":{
                        "url":"http://i.am.a/URL",
                        "clicktrackers":[
                           "http://a.com/clk1",
                           "http://a.com/clk2"
                        ]
                     },
                     "imptrackers":[
                        "http://a.com/imp1",
                        "http://b.com/imp2"
                     ],
                     "jstracker": "<script src=\"http://supported-tracker-domain/mCh7nspyora8hafx6qjs\"></script>",
                     "version" : "1.1",
                     "assets":[
                        { "id": 123, "required": 1, "title": { "text": "Learn about this awesome thing" } },
                        { "id": 124, "required": 1, "img": { "url": "http://www.myads.com/thumbnail1.png" } },
                        { "id": 125, "required": 1, "img": { "url": "http://www.myads.com/brandlogo1.png" } },
                        { "id": 128, "required": 1, "img": { "url": "http://www.myads.com/largethumb1.png" } },
                        { "id": 126, "required": 1, "data": { "value": "My Brand" } },
                        { "id": 127, "required": 1, "data": { "value": "Learn all about this awesome story of someone using my product." } },
                        { "id": 129, "required": 0, "data": { "value":"Opt-out text." } },
                        { "id": 130, "required": 0, "data": { "value":"Opt-out URL." } }
                     ]
                  }
               }
            }
         ]
      }
   ]
}