Sovrn oRTB Specs
The Sovrn Real-Time Bidding interface allows ad buyers to bid in real-time on impressions across the Sovrn publisher network. The bidding process requires multiple steps and interactions. The basic bidding process is outlined below.
A reader visits a site in the Sovrn publisher network and renders a Sovrn ad tag.
The Sovrn ad request is selected as a valid Real-Time Bidding impression by the Sovrn RTB engine.
The Sovrn RTB Engine sends HTTP-based bid requests to all available Ad Buyers.
The Ad Buyer receives the bid request and returns an HTTP response indicating their desired bid and other creative and data details required to fulfill a bid.
Based on a first-price auction model, Sovrn will choose the winning bidder based on their actual bid price. Auction Type (at) will be specified in bid requests to buyers.
The winning bidder's ad creative is then delivered to the reader on the Sovrn publisher site and the ad is impressed.
Bid Requests
When an impression is available for bidding within the Sovrn network, a bid request is sent to each ad buyer. All bid requests are HTTP GET requests that contain all necessary data as encoded URL parameters or HTTP POST requests that pass the data in a JSON object (we currently only support JSON encoded bid requests). Bid requests will be sent to the ad buyer via HTTP to a URL specified by the buyer.
Object List and Definitions
RTB transactions are initiated when an exchange or other supply source send a bid request to a bidder. The bid request consists of a bid request object, at least one impression object, and may optionally include additional objects providing impression context. Please note that any mobile app or video integration could require additional integrations within the Sovrn system.
Objects and attributes that are required will be noted. All other objects and attributes are recommended for optimal performance.
Object | Description |
|---|---|
Bid Request (required) | Top-level object |
Source | Request source details on post-auction decisioning (e.g., header bidding) |
Regs | Contains any legal, governmental, or industry regulations that apply to the request |
Impression (required) | Description of a specific impression. At least one is required in a bid request |
Metric | A quantifiable, often historical, data point about an impression |
Banner | Details for a banner impression. Required if the impression is a banner ad opportunity |
Video | Details for a video impression. Required if the impression is a video ad opportunity |
Format | Allowed sizes for an impression |
Pmp | Collection of private marketplace (PMP) deals applicable to this impression |
Deal | Deal terms pertaining to this impression between a seller and buyer |
Site | Details of the website calling for the impression |
Device | Details of the device on which the content and impressions are displayed |
Geo | Location of the device or user's home base depending on the parent object |
User | Human user of the device; audience for advertising |
Bid Request Object
A bid request id attribute is required as is at least one impression object.
Field | Type | Description |
|---|---|---|
id | string (required) | Unique ID of the bid request, provided by the exchange |
imp | object array (required) | Array of Imp objects representing the impressions offered. At least 1 Imp object is required |
site | object | Details about the publisher's website. Only applicable and recommended for websites |
device | object | Details about the user's device to which the impression will be delivered |
user | object | Details about the human user of the device; the advertising audience |
at | integer | Auction type, where 1 = first price, 2 = second price. Default is 2 |
tmax | integer | Maximum time in milliseconds Sovrn allows for bids to be received to avoid timeout |
bcat | string array | Blocked advertiser categories using the IAB content categories1 |
badv | string array | Blocklist of advertisers by their domains |
source | object | A Source object that provides data about the inventory source and which entity makes the final decision |
ext | object | Placeholder for exchange-specific extensions to OpenRTB |
Sovrn implements the IAB categories denoted in Table 5.1 here.
Ext Object (Applied to Bid Request Object)
Field | Type | Description |
|---|---|---|
pchain | string | Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0 |
schain | string | pchain and schain are both supported, but schain is recommended/preferred |
Source Object
Field | Type | Description |
|---|---|---|
pchain | string | Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.03 |
TAG Payment ID Protocol document can be found here.
Regs Object
Field | Type | Description |
|---|---|---|
ext.gdpr | integer | IAB consent string provided when a request is subject to GDPR |
Imp Object
At least one impression object is required.
Field | Type | Description |
|---|---|---|
id | string (required) | Unique identifier for this impression within the context of the bid request |
metric | object array | An array of Metric objects |
banner | object | Required if this impression is offered as a banner ad opportunity |
video | object | Required if this impression is offered as a video ad opportunity |
pmp | object | Contains any private marketplace deals in effect for this impression |
displaymanager | string | Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile) |
displaymanagerver | string | Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile) |
instl | integer | 1 = ad is interstitial or full screen, 0 = not interstitial. Default is 0 |
tagid | string | Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging or optimization |
bidfloor | float | Minimum bid for this impression expressed in CPM |
secure | integer | Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure |
ext | object | Placeholder for exchange-specific extensions to OpenRTB |
Ext Object (Applied to Imp Object)
Field | Type | Description |
|---|---|---|
deals | string array | List of unique identifiers for a private marketplace or deal ID to be passed through the bid response |
Metric Object
Field | Type | Description |
|---|---|---|
type | string | Type of metric being presented using exchange curated string names |
value | float | Number representing the value of the metric. Probabilities must be in the range of 0.0 - 1.0 |
vendor | string | Source of the value using exchange curated string names. If the exchange itself is the source versus a third party, "EXCHANGE" is recommended |
Banner Object
Field | Type | Description |
|---|---|---|
format | object array (recommended) | Array of format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes |
w | integer (required) | Exact width in device independent pixels (DIPS) |
h | integer (required) | Exact height in device independent pixels (DIPS) |
battr | integer array | Blocked creative attributes. Refer to Table 6.3. If blank assume all types are allowed |
pos | integer | Ad position on screen. Use Table 6.5 |
topframe | integer | Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes |
expdir | integer array | Directions in which the banner may expand. Refer to Table 6.11 |
id | string | Unique identifier for this banner object. Useful for tracking multiple banner objects. Combination of banner ID should be unique |
Video Object
Field | Type | Description |
|---|---|---|
mimes | string array (required) | Content MIME types supported (e.g. "video/x-ms-wmv", "video/mp4") |
minduration | integer (required) | Minimum video ad duration in seconds |
maxduration | integer (required) | Maximum video ad duration in seconds |
placement | integer (supported, plcmt recommended) | see the definitions here. |
plcmt | integer (recommended) | see the definitions here. |
protocols | integer | Supported video protocols. Refer to Table 6.7 |
w | integer (required) | Width of the video player in device independent pixels (DIPS) |
h | integer (required) | Height of the video player in device independent pixels (DIPS) |
startdelay | integer | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to Table 6.9 |
linearity | integer | Indicates if the impression must be linear, nonlinear, etc. Refer to List 5.7 |
maxbitrate | integer | Maximum bit rate in Kbps |
playbackmethod | integer array | Playback methods that may be in use. If none are specified, any method may be used. Refer to List 5.10. Only one method is typically used in practice |
pos | integer | Ad position on the screen. Refer to List 5.4 |
companionad | object array | Array of Banner objects if companion ads are available |
api | integer array | List of supported API frameworks for this impression. Refer to List 5.6. If an API is not explicitly listed, it is assumed not to be supported |
Format Object
Field | Type | Description |
w | integer | Width in device independent pixels (DIPS) |