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” |
- 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.
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 PUT
ting (instead of POST
ing) 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 :
|
<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
More than 2 trackers are sent
Either of the 2 trackers is not from a whitelisted domain
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." } }
]
}
}
}
]
}
]
}