NAV
Sample JSON

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 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 generally appear in one of two ‘modes’, and this information is provided in the bid request:

  1. Collapsed - most frequently used on feed pages, these ads have a smaller initial state showing the thumbnail, brand, and title. When the user clicks, the unit clicks through directly to the content.

  2. Pre-expanded - sometimes seen on feed pages, and most often on post pages, these units are larger. The first click will clickout or play the video, depending on creative type.

You can see an example of how Sharethrough mobile in-feed ads work for various types of content and on various example publishers via our native ad generator tool here. 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.

Support Scenarios

In-feed for In-Browser (desktop/tablet/smartphone) and In-App (tablet/smartphone)

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, tagid, iframebuster native, bidfloor, secure, pmp, video
Native Yes See below
Private Marketplace Yes See below
Banner No
Video Yes protocol, w, h, startdelay, skip, skipmin, skipafter, sequence, battr, maxextended, minbitrate, maxbitrate, maxbitrate, delivery, pos, , companionad, api, companiontype mimes, minduration, maxduration, protocols, linearity, 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

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.
linearity integer Indicates whether the video will be played linearly / in-stream (value 1) or non-linearly / outsream (value 2)
Always will be 2.
protocols integer array Indicates what Video Ad protocols are accepted.
Always will be [2, 3, 7] to indicate VAST version 2, 3, and 4.
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.

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.

Field Name Type Default Description
request string Contains the Native Request Object below encoded as a string

Native Request Object

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

Field Name Type Default Description
ver integer 1
layout integer 3 The layout ID of the native ad unit.
Always 3 (news feed) for Sharethrough
adunit integer 3 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. Often 1, but greater than 1 in the case that this page is a feed with multiple placements within it.
assets array An array of Asset Objects which specifies what Sharethrough expects back with the bid. See below.
ext object See below Native Object extensions. Can optionally be ignored.

Native Object extension

These fields are unique to Sharethrough to provide additional context and can be ignored if the bidder does not wish to use this info.

Field Name Type Default Description
feeditemtype integer Feeds can be constructed of various item types. Refer to the Feed Item Type table

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 - always present
img object Image object - always present
data object Data object - always present
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; always 140 for Sharethrough
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:

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:

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, 7] to indicate VAST version 2, 3, and 4.
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 string 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 Deprecated support for googleaidsha1/idfasha1 for in-app advertising identifiers

User Object

The user object 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

System Defaults

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

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

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, adomain, iurl, attr adm, id, impid, price, nurl, 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
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. For data of type 750, link is required. For all other objects, link is not supported.

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

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. You will have the ability to mine this data via the Metamarkets analytics dashboard.

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.

Error Notification

Error and lost bid data will be provided in the Metamarkets login issued to the bidder.

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.

Clickout creative

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:/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 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.

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.

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:/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 Thumbnail image to show in the ad on smartphone
2 Brand logo image
3 Thumbnail image to show for tablet and desktop

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

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

{
    "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
    "imp": [
        {
            "id": "1",
            "bidfloor": 3.5,
            "secure": 0,
            "native": {
                "request": "{\"native\":{\"layout\":3,\"adunit\":3,\"plcmtcnt\":1,\"assets\":[{\"id\":123,\"required\":1,\"title\":{\"len\":140}},{\"id\":128,\"required\":0,\"img\":{\"wmin\":1000,\"hmin\":750,\"type\":3}},{\"id\":125,\"required\":0,\"img\":{\"wmin\":48,\"hmin\":48,\"type\":2}},{\"id\":124,\"required\":1,\"img\":{\"wmin\":320,\"hmin\":180,\"type\":1}},{\"id\":126,\"required\":1,\"data\":{\"type\":1,\"len\":25}},{\"id\":127,\"required\":1,\"data\":{\"type\":2,\"len\":400}},{\"id\":129,\"required\":0,\"data\":{\"len\":2000,\"type\":501}},{\"id\":130,\"required\":0,\"data\":{\"len\":2000,\"type\":502}}]}}"
            }
        }
    ],
    "site": {
        "id": "234563",
        "cat": [
            "IAB2",
            "IAB4"
        ],
        "publisher": {
            "id": "12345"
        },
        "domain": "mypublisher.com",
        "page": "www.mypublisher.com/xyz"
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1_4 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10B350 Safari/8536.25",
        "ip": "192.168.1.8",
        "dnt": 0,
        "js": 1,
        "make": "Apple",
        "model": "iPhone 3GS",
        "os": "iOS",
        "osv": "6.1.4",
        "connectiontype": 2,
        "geo": {
            "country": "USA",
            "metro": "500",
            "type": 2
        },
        "devicetype": 1
    },
    "user": {
        "buyeruid": "25352123"
    }
}

Mobile App

{
    "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
    "imp": [
        {
            "id": "1",
            "bidfloor": 3.5,
            "secure": 0,
            "native": {
                "request": "{\"native\":{\"layout\":3,\"adunit\":3,\"plcmtcnt\":1,\"assets\":[{\"id\":123,\"required\":1,\"title\":{\"len\":140}},{\"id\":128,\"required\":0,\"img\":{\"wmin\":1000,\"hmin\":750,\"type\":3}},{\"id\":125,\"required\":0,\"img\":{\"wmin\":48,\"hmin\":48,\"type\":2}},{\"id\":124,\"required\":1,\"img\":{\"wmin\":320,\"hmin\":180,\"type\":1}},{\"id\":126,\"required\":1,\"data\":{\"type\":1,\"len\":25}},{\"id\":127,\"required\":1,\"data\":{\"type\":2,\"len\":400}},{\"id\":129,\"required\":0,\"data\":{\"len\":2000,\"type\":501}},{\"id\":130,\"required\":0,\"data\":{\"len\":2000,\"type\":502}}]}}"
            }
        }
    ],
    "app": {
        "id": "234563",
        "name": "mypublisher",
        "bundle": "com.foo.mypublisher",
        "cat": [
            "IAB2",
            "IAB4"
        ],
        "publisher": {
            "id": "12345"
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1_4 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10B350 Safari/8536.25",
        "ip": "192.168.1.8",
        "dnt": 0,
        "dpidsha1": "af543680e",
        "js": 1,
        "make": "Apple",
        "model": "iPhone 3GS",
        "os": "iOS",
        "osv": "6.1.4",
        "connectiontype": 2,
        "geo": {
            "country": "USA",
            "metro": "500",
            "type": 2
        },
        "devicetype": 1,
        "ifa": "9581c0f0-f722-41eb-9881-5c5f5be54c75",
        "ext": {
            "idfasha1": "a5b534fa98ebe48809b765e983b8f8bfd76698d1"
        }
    }
}

The idfasha1 field in the ext object for the app bid request will be replaced by googleaidsha1 when available for Android devices.

Desktop Web

{
    "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
    "imp": [
        {
            "id": "1",
            "bidfloor": 3.5,
            "native": {
                "request": "{\"native\":{\"layout\":3,\"adunit\":3,\"plcmtcnt\":1,\"assets\":[{\"id\":123,\"required\":1,\"title\":{\"len\":140}},{\"id\":128,\"required\":0,\"img\":{\"wmin\":1000,\"hmin\":750,\"type\":3}},{\"id\":125,\"required\":0,\"img\":{\"wmin\":48,\"hmin\":48,\"type\":2}},{\"id\":124,\"required\":1,\"img\":{\"wmin\":320,\"hmin\":180,\"type\":1}},{\"id\":126,\"required\":1,\"data\":{\"type\":1,\"len\":25}},{\"id\":127,\"required\":1,\"data\":{\"type\":2,\"len\":400}},{\"id\":129,\"required\":0,\"data\":{\"len\":2000,\"type\":501}},{\"id\":130,\"required\":0,\"data\":{\"len\":2000,\"type\":502}}]}}"
            }
        }
    ],
    "site": {
        "id": "234563",
        "cat": [
            "IAB2",
            "IAB4"
        ],
        "publisher": {
            "id": "12345"
        },
        "domain": "mypublisher.com",
        "page": "www.mypublisher.com/xyz"
    },
    "device": {
        "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
        "ip": "192.168.1.8",
        "dnt": 0,
        "js": 1,
        "make": "Apple",
        "model": "mac",
        "os": "OSX",
        "osv": "10.6.8",
        "connectiontype": 2,
        "geo": {
            "country": "USA",
            "metro": "500",
            "type": 2
        },
        "devicetype": 2
    },
    "user": {
        "buyeruid": "25352123"
    }
}

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

{
   "id":"80ce30c53c16e6ede735f123ef6e32361bfc7b22",
   "imp":[
      {
         "id":"1",
         "secure":0,
         "bidfloor":0.5,
         "native":{
            "request":{
               "native":{
                  "context":2,
                  "contextsubtype":20,
                  "plcmttype":11,
                  "plcmtcnt":1,
                  "version" : "1.1",
                  "assets":[
                     { "id":1, "required":1, "title": { "len":140 } },
                     { "id":2, "required":0, "img": { "hmin":180, "wmin": 320, "type":1 } },
                     { "id":3, "required":0, "img": { "hmin":48, "wmin": 48, "type":2 } },
                     { "id":4, "required":1, "img": { "hmin":750, "wmin": 1000, "type":3 } },
                     { "id":6, "required":1, "data":{ "len":140, "type": 2 } },
                     { "id":5, "required":1, "data":{ "len":25, "type": 1 } },
                     { "id":7, "required":0, "data":{ "len":2000, "type": 501 } },
                     { "id":8, "required":0, "data":{ "len":2000, "type": 502 } }
                  ],
                  "adunit": 2,
                  "ver": 1.1,
                  "layout": 3
               }
            }
         }
      }
   ],
   "user":{
      "buyeruid":"25352123"
   },
   "site":{
      "domain":"http://mashable.com",
      "page":"",
      "id":"847e19cc",
      "publisher":{
         "id":"2c835af1"
      },
      "cat":[
         "IAB1"
      ]
   },
   "device":{
      "connectiontype":0,
      "devicetype":2,
      "ip":"50.1.107.42",
      "model":"Macintosh",
      "ua":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.75 Safari/537.36",
      "geo":{
         "type":2,
         "metro":"807",
         "country":"US"
      },
      "os":"OS X",
      "osv":"49",
      "make":"Apple",
      "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",
                    "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",
               "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." } }
                     ]
                  }
               }
            }
         ]
      }
   ]
}