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.

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”

The VAST protocol reflects the protocols accepted by the creative approval endpoint for preprocessing.

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.

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.

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.

Bid Response Validator

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

{"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

{"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:

{"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"?><VASTversion="2.0"><Ad><InLine><AdSystemversion="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><Creativesequence="1"id="unique-creative-id"><Linear><MediaFiles><MediaFiletype="video/mp4"><![CDATA[http://example.com/video-ad.mp4]]></MediaFile></MediaFiles><TrackingEvents><TrackingEventevent="start"><![CDATA[http://example.com/playback-start.gif]]></TrackingEvent><TrackingEventevent="progress"offset="00:00:03"><![CDATA[http://example.com/3-second-view.gif]]></TrackingEvent><TrackingEventevent="progress"offset="00:00:10"><![CDATA[http://example.com/10-second-view.gif]]></TrackingEvent><TrackingEventevent="progress"offset="00:00:15"><![CDATA[http://example.com/15-second-view.gif]]></TrackingEvent><TrackingEventevent="progress"offset="00:00:30"><![CDATA[http://example.com/30-second-view.gif]]></TrackingEvent><TrackingEventevent="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>

Event details

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.

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