Adform OpenRTB Handler: Bid Request Specifications

gdpr

int

Flag that indicates whether or not the request is subject to GDPR regulations 0 = No, 1 = Yes, omission indicates unknown.

yes

request.regs.ext.gdpr  – To support GDPR

gpp

string

Contains the Global Privacy Platform’s consent string.

yes

request.regs.gpp - To support GPP

gpp_sid

integer

Array of the sections of the string which should be applied for this transaction. Generally will contain only one value, but there are cases where more than one may apply. GPP Section 3 (Header) and 4 (Signal Integrity) do not need to be included.

yes

request.regs.gpp_sid – to pass the used GPP Section ID

id

string; required

Unique ID of the bid request, provided by the exchange.

yes

imp

object array; required

Array of Imp objects representing the impressions offered.  At least 1 Imp object is required.

yes

site

object; recommended

Details via a Site object about the publisher’s website.  Only applicable and recommended for websites.

yes

app

object; recommended

Details via an App object about the publisher’s app (i.e., non-browser applications).  Only applicable and recommended for apps.

yes

device

object; recommended

Details via a Device object about the user’s device to which the impression will be delivered.

yes

user

object; recommended

Details via a User object about the human user of the device; the advertising audience.

yes

test

integer; default 0

Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.

yes

at

integer; default 2

Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values greater than 500.

yes

tmax

integer

Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout.  This value supersedes any a priori guidance from the exchange.

yes

wseat

string array

White list of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression.  IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori.  At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions.

no

bseat

string array

Block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression.  IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori.  At most, only one of wseat and bseat should be used in the same request.  Omission of both implies no seat restrictions.

no

allimps

integer; default 0

Flag to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (e.g., all on the web page, all video spots such as pre/mid/post roll) to support road-blocking.  0 = no or unknown, 1 = yes, the impressions offered represent all that are available.

no

cur

string array

Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes.  Recommended only if the exchange accepts multiple currencies.

yes

Only first value of the array is read. If does not exist, then default value (USD) is set.

wlang

string array

White list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the Device and/or Content objects if available.

no

bcat

string array

Blocked advertiser categories using the IAB content categories.

no

badv

string array

Block list of advertisers by their domains (e.g., “ford.com”).

no

bapp

string array

Block list of applications by their platform-specific exchange- independent application identifiers.  On Android, these should be bundle or package names (e.g., com.foo.mygame).  On iOS, these are numeric IDs.

no

source

object

A Sorce object that provides data about the inventory source and which entity makes the final Comment.

yes

regs

object

A Regs object that specifies any industry, legal, or governmental regulations in force for this request.

yes

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

yes

pt

string

Price type.

yes

Default value is net.

fd

Integer; recommended

Entity responsible for the final impression sale Comment, where 0 = exchange, 1 = upstream source.

yes

tid

string; recommended

Transaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges).

yes

pchain

string; recommended

Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.

no

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

yes

schain

object

This object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete.

yes

Pass the SupplyChain Object with complete value, nodes, and mandatory fields. See the examples: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md#single-hop---chain-complete-optional-fields-missing

coppa

integer

Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.

yes

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

yes

gdpr

integer

yes

request.regs.ext.gdpr  – To support GDPR

dsa

object

Extension for DSA Transparency Information

yes

gpc

string

Global Privacy Control (GPC) signal

yes

dsarequired

integer

Flag to indicate if DSA information should be made available.

yes

This will signal if the bid request belongs to an Online Platform/VLOP, such that a buyer should respond with DSA Transparency information based on the pubrender value.

0 = Not required.

1 = Supported, bid responses with or without DSA object will be accepted.

2 = Required, bid responses without DSA object won't be accepted.

3 = Required, bid responses without DSA object won't be accepted, Publisher is an Online Platform.

pubrender

integer

Flag to indicate if the publisher will render the DSA Transparency info.

yes

This will signal if the publisher is able to and intends to render an icon or other appropriate user-facing symbol and display the DSA transparency info to the end user.

0 = Publisher can't render

1 = Publisher could render depending on adrender

2 = Publisher will render

datatopub

integer

Independent of pubrender, the publisher may need the transparency data for audit purposes.

yes

0 = do not send transparency data

1 = optional to send transparency data

2 = send transparency data

transparency

array of object

Array of objects of the entities that applied user parameters and the parameters they applied.

yes

domain

string

Domain of the entity that applied user parameters

yes

dsaparams

array of integer

Array for platform or sell-side use of any user parameters

yes

1 = Profiling. Information about the user, collected and used across contexts, that is about the user's activity, interests, demographic information, or other characteristics.

2 = Basic Advertising. Use of real-time information about the context in which the ad will be shown, to show the ad, including information about the content and the device, such as: device type and capabilities, user agent, URL, IP address, non-precise geolocation data.

3 = Precise geolocation. The precise real-time geolocation of the user, for example, GPS coordinates within 500-meter radius precision.

id

string; required

A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments.

yes

metric

object array

An array of Metric object.

no

banner

object

A Banner object; required if this impression is offered as a banner ad opportunity.

yes

video

object

A Video object; required if this impression is offered as a video ad opportunity.

yes

audio

object

An Audio object; required if this impression is offered as an audio ad opportunity.

no

native

object

A Native object; required if this impression is offered as a native ad opportunity.

yes

pmp

object

A Pmp object containing any private marketplace deals in effect for this impression.

yes

displaymanager

string

Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile).  Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.

no

displaymanagerver

string

Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile).  Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.

no

instl

integer; default 0

1 = the ad is interstitial or full screen, 0 = not interstitial.

yes

tagid

string

Identifier for specific ad placement or ad tag that was used to initiate the auction.  This can be useful for debugging of any issues, or for optimization by the buyer.

yes

bidfloor

float; default 0

Minimum bid for this impression expressed in CPM.

yes

bidfloorcur

string; default “USD”

Currency specified using ISO-4217 alpha codes.  This may be different from bid currency returned by bidder if this is allowed by the exchange.

yes

clickbrowser

integer

Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native.  Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute.

no

secure

integer

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.

no

Value is taken from request header.

iframebuster

string array

Array of exchange-specific names of supported iframe busters.

no

exp

integer

Advisory as to the number of seconds that may elapse between the auction and the actual impression.

no

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

no

type

string; required

Type of metric being presented using exchange curated string names which should be published to bidders a priori.

no

value

float; required

Number representing the value of the metric.  Probabilities must be in the range 0.0 – 1.0.

no

vendor

string; recommended

Source of the value using exchange curated string names which should be published to bidders a priori.  If the exchange itself is the source versus a third party, “EXCHANGE” is recommended.

no

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

no

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 is highly recommended.

yes

w

integer

Exact width in device independent pixels (DIPS); recommended if no format objects are specified.

yes

h

integer

Exact height in device independent pixels (DIPS); recommended if no format objects are specified.

yes

wmax

integer; DEPRECATED

NOTE:  Deprecated in favor of the format array. Maximum width in device independent pixels (DIPS).

no

hmax

integer; DEPRECATED

NOTE:  Deprecated in favor of the format array. Maximum height in device independent pixels (DIPS).

no

wmin

integer; DEPRECATED

NOTE:  Deprecated in favor of the format array. Minimum width in device independent pixels (DIPS).

no

hmin

integer; DEPRECATED

NOTE:  Deprecated in favor of the format array. Minimum height in device independent pixels (DIPS).

no

btype

integer array

Blocked banner ad types. 

no

battr

integer array

Blocked creative attributes. 

no

pos

integer

Ad position on screen. 

yes

mimes

string array

Content MIME types supported. Popular MIME types may include “image/jpg” and “image/gif”.

no

topframe

integer

Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.

no

expdir

integer array

Directions in which the banner may expand. 

no

api

integer array

List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.

no

id

string

Unique identifier for this banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression.

no

vcm

integer

Relevant only for Banner objects used with a Video object in an array of companion ads.  Indicates the companion banner rendering mode relative to the associated video, where 0 = concurrent, 1 = end-card.

no

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

no

mimes

string array; required

Content MIME types supported (e.g., “video/x-ms-wmv”, “video/mp4”).

no*

Value is taken from UI configuration.

minduration

integer; recommended

Minimum video ad duration in seconds.

no*

Value is taken from UI configuration.

maxduration

integer; recommended

Maximum video ad duration in seconds.

no*

Value is taken from UI configuration.

protocols

integer array; recommended

Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute.

no*

Value is taken from UI configuration.

protocol

integer; DEPRECATED

NOTE:  Deprecated in favor of protocols. Supported video protocol. At least one supported protocol must be specified in either the protocol or protocols attribute.

no

w

integer; recommended

Width of the video player in device independent pixels (DIPS).

yes

Value is taken from UI configuration.

h

integer; recommended

Height of the video player in device independent pixels (DIPS).

yes

Value is taken from UI configuration.

startdelay

integer; recommended

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.

no*

Value is taken from UI configuration.

placement

integer

Placement type for the impression. 

no*

Value is taken from UI configuration.

linearity

integer

Indicates if the impression must be linear, nonlinear, etc.  If none specified, assume all are allowed. 

no*

Default value is 1.

skip

integer

Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. If a bidder sends markup/creative that is itself skippable, the Bid object should include the attr array with an element of 16 indicating skippable video. 

no*

Value is taken from UI configuration.

skipmin

integer; default 0

Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.

no

skipafter

integer; default 0

Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.

no

sequence

integer

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.

no

battr

integer array

Blocked creative attributes. 

no

maxextended

integer

Maximum extended ad duration if extension is allowed.  If blank or 0, extension is not allowed.  If -1, extension is allowed, and there is no time limit imposed.  If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

no*

Default value is 0.

minbitrate

integer

Minimum bit rate in Kbps.

no*

Value is taken from UI configuration.

maxbitrate

integer

Maximum bit rate in Kbps.

no*

Value is taken from UI configuration.

boxingallowed

integer; default 1

Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.

no

playbackmethod

integer array

Playback methods that may be in use.  If none are specified, any method may be used.  Only one method is typically used in practice.  As a result, this array may be converted to an integer in a future version of the specification.  It is strongly advised to use only the first element of this array in preparation for this change.

no

playbackend

integer

The event that causes playback to end. 

no

delivery

integer array

Supported delivery methods (e.g., streaming, progressive).  If none specified, assume all are supported. 

no

pos

integer

Ad position on screen. 

yes

companionad

object array

Array of Banner objects if companion ads are available.

no

api

integer array

List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.

no

Value is taken from UI configuration.

companiontype

integer array

Supported VAST companion ad types. Recommended if companion Banner objects are included via the companionad array.  If one of these banners will be rendered as an end-card, this can be specified using the vcm attribute with the particular banner.

no

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

no

mimes

string array; required

Content MIME types supported (e.g., “audio/mp4”).

no

minduration

integer; recommended

Minimum audio ad duration in seconds.

no

maxduration

integer; recommended

Maximum audio ad duration in seconds.

no

protocols

integer array; recommended

Array of supported audio protocols. 

no

startdelay

integer; recommended

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. 

no

sequence

integer

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.

no

battr

integer array

Blocked creative attributes. 

no

maxextended

integer

Maximum extended ad duration if extension is allowed.  If blank or 0, extension is not allowed.  If -1, extension is allowed, and there is no time limit imposed.  If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

no

minbitrate

integer

Minimum bit rate in Kbps.

no

maxbitrate

integer

Maximum bit rate in Kbps.

no

delivery

integer array

Supported delivery methods (e.g., streaming, progressive).  If none specified, assume all are supported.

no

companionad

object array

Array of Banner objects if companion ads are available.

no

api

integer array

List of supported API frameworks for this impression.  If an API is not explicitly listed, it is assumed not to be supported.

no

companiontype

integer array

Supported DAAST companion ad types. Recommended if companion Banner objects are included via the companionad array.

no

maxseq

integer

The maximum number of ads that can be played in an ad pod.

no

feed

integer

Type of audio feed. 

no

stitched

integer

Indicates if the ad is stitched with audio content or delivered independently, where 0 = no, 1 = yes.

no

nvol

integer

Volume normalization mode. 

no

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

no