ℹ️Integration Document RTB
Specification for Integration with SSP’s/DSP’s
Overview
DTXplatform is a modern real-time bidding system that allows buyers to make purchases automatically when searching for advertising resources.
Its interface is implemented as per the IAB’s OpenRTB Specification Version 2.5 and uses JSON as its message format [Content-Type: application/json; charset=UTF-8].
Open RTB Version HTTP Header
We support Open RTB 2.5 by default, but we can also support 2.4, 2.3, 2.0, and 1.0 versions for specific integrations.
Default header is [x-openrtb-version: 2.5].
Transport
By default, all calls should return HTTP code 200 with body containing bid response in JSON format. For “no bid” response, the call should return HTTP code 204 with empty body.
We can also support other options for specific integrations, like HTTP code 200 with empty body, or with body containing “nobid” message.
Data format
By default, JSON (JavaScript Object Notation) supported for bid request and bid response data payloads. We can support other data format for specific integrations. Default header: Content-Type: application/JSON header.
Accordance with IAB Specifications and Guidelines
We work in accordance with IAB Specifications available here:
https://www.iab.com/wp-content/uploads/2016/01/OpenRTB-API-Specification-Version-2-4-DRA FT.pdf https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf
Bid Request
DTXplatform sends a Bid Request when an image becomes visible within the browser. The following table describes the fields and objects in the BidRequest message.
Attribute
Type
Description
id
string; required
Unique ID of the bid request, provided by the exchange.
imp
object array;
required
Array with 1 Imp object.
site
object; required
Details via a Site object about the publisher’s website. Only applicable and required for websites.
app
object; required
Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and required for apps.
device
object; required
Details via a Device object about the user’s device to which the impression will be delivered.
user
object; recommended
Details via a User object about the human user of the device; the advertising audience.
test
integer; default 0
Indicator of test mode in which auctions are not billable,
where 0 = live mode, 1 = test mode.
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.
tmax
integer
Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline.
wseat
string array
Whitelist 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.
Omission implies no seat restrictions.
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.
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.
bcat
string array
Blocked advertiser categories using the IAB content categories.
badv
string array
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.
regs
object
A Regs object that specifies any industry, legal, or governmental regulations in force for this request.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Impression
Attribute
Type
Description
id
string
A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments.
banner
object
A Banner object; required if this impression is offered as a banner ad opportunity.
video
object
A Video object; required if this impression is offered as a video ad opportunity.
native
object
A Native object; required if this impression is offered as a native ad opportunity.
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.
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.
instl
integer; default 0
1 = the ad is interstitial or full screen, 0 = not interstitial
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.
bidfloor
float; default 0
Minimum bid for this impression expressed in CPM.
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.
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.
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.
iframebuster
string array
Array of exchange-specific names of supported iframe busters.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Banner
Attribute
Type
Description
w
integer; required
Width in device independent pixels (DIPS).
If no format objects are specified, this is an exact width requirement. Otherwise it is a preferred width.
h
integer; required
Height in device independent pixels (DIPS).
If no format objects are specified, this is an exact height requirement. Otherwise it is a preferred height.
format
object array
Array of format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended.
wmax
integer; DEPRECATED
NOTE: Deprecated in favor of the format array.
Maximum width in device independent pixels (DIPS).
hmax
integer; DEPRECATED
NOTE: Deprecated in favor of the format array.
Maximum height in device independent pixels (DIPS).
wmin
integer; DEPRECATED
NOTE: Deprecated in favor of the format array.
Minimum width in device independent pixels (DIPS).
hmin
integer; DEPRECATED
NOTE: Deprecated in favor of the format array.
Minimum height in device independent pixels (DIPS).
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.
btype
integer array
Blocked banner ad types.
battr
integer array
Blocked creative attributes.
pos
integer
Ad position on screen.
mimes
string array
Content MIME types supported. Popular MIME types may include
“application/x-shockwave-flash”, “image/jpg”, and “image/gif”.
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.
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.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Video
Attribute
Type
Description
mimes
string array; required
Content MIME types supported. Popular MIME types may include
“video/x-ms-wmv” for Windows Media and “video/x-flv” for Flash Video.
minduration
integer; recommended
Minimum video ad duration in seconds.
maxduration
integer; recommended
Maximum video ad duration in seconds.
protocols
integer array; recommended
Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute.
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.
w
integer; recommended
Width of the video player in device independent pixels (DIPS).
h
integer; recommended
Height of the video player in device independent pixels (DIPS).
startdelay
integer; recommended
Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.
linearity
integer
Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed.
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.
skipmin
integer; default 0
Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipafter
integer; default 0
Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.
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.
battr
integer array
Blocked creative attributes.
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.
minbitrate
integer
Minimum bit rate in Kbps.
maxbitrate
integer
Maximum bit rate in Kbps.
boxingallowed
integer; default 1
Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.
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.
delivery
integer array
Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported.
pos
integer
Ad position on screen.
companionad
object array
Array of Banner objects if companion ads are available.
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.
companiontype
integer array
Supported VAST companion ad types. Recommended if companion Banner objects are included via the companionad array.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Native
Attribute
Type
Description
request
string; required
Request payload complying with the Native Ad Specification.
ver
string; recommended
Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.
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.
battr
integer array
Blocked creative attributes.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Audio
Attribute
Type
Description
mimes
string array; required
Content MIME types supported. Popular MIME types may include
“video/x-ms-wmv” for Windows Media and “video/x-flv” for Flash Video.
minduration
integer; recommended
Minimum audio ad duration in seconds.
maxduration
integer; recommended
Maximum audio ad duration in seconds.
protocols
integer; DEPRECATED
Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute.
startdelay
integer; recommended
Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.
minbitrate
integer
Minimum bit rate in Kbps.
maxbitrate
integer
Maximum bit rate in Kbps.
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.
Site
Attribute
Type
Description
id
string; recommended
Exchange-specific site ID.
name
string
Site name (may be aliased at the publisher’s request).
domain
string; required
cat
string array
Array of IAB content categories of the site.
sectioncat
string array
Array of IAB content categories that describe the current section of the site.
pagecat
string array
Array of IAB content categories that describe the current page or view of the site.
page
string
URL of the page where the impression will be shown.
ref
string
Referrer URL that caused navigation to the current page.
search
string
Search string that caused navigation to the current page.
mobile
integer
Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes.
privacypolicy
integer
Indicates if the site has a privacy policy, where 0 = no, 1 = yes.
publisher
object
Details about the Publisher of the site.
content
object
Details about the Content within the site.
keywords
string
Comma separated list of keywords about the site.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Device
Attribute
Type
Description
ua
string; required
Browser user agent string.
geo
object; recommended
Location of the device assumed to be the user’s current location defined by a Geo object.
dnt
integer; recommended
Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
lmt
integer; recommended
“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
ip
string; required
IPv4 address closest to device.
ipv6
string
IP address closest to device as IPv6.
devicetype
integer
The general type of device.
make
string
Device make (e.g., “Apple”).
model
string
Device model (e.g., “iPhone”).
os
string
Device operating system (e.g., “iOS”).
osv
string
Device operating system version (e.g., “3.1.2”).
hwv
string
Hardware version of the device (e.g., “5S” for iPhone 5S).
h
integer
Physical height of the screen in pixels.
w
integer
Physical width of the screen in pixels.
ppi
integer
Screen size as pixels per linear inch.
pxratio
float
The ratio of physical pixels to device independent pixels.
js
integer
Support for JavaScript, where 0 = no, 1 = yes.
geofetch
integer
Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes.
flashver
string
Version of Flash supported by the browser.
language
string
Browser language using ISO-639-1-alpha-2.
carrier
string
Carrier or ISP (e.g., “VERIZON”). “WIFI”
is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular).
connectiontype
integer
Network connection type.
ifa
string; recommended
ID sanctioned for advertiser use in the clear (i.e., not hashed); required for apps.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Geo
Attribute
Type
Description
lat
float
Latitude from -90.0 to +90.0, where negative is south.
lon
float
Longitude from -180.0 to +180.0, where negative is west.
type
integer
Source of location data; recommended when passing lat/lon.
accuracy
integer
Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device’s location services (i.e., type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation.
country
string
Country code using ISO-3166-1-alpha-3.
region
string
Region code using ISO-3166-2; 2-letter state code if USA.
city
string
City using United Nations Code for Trade & Transport Locations.
zip
string
Zip or postal code.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
User
Attribute
Type
Description
id
string; recommended
Exchange-specific ID for the user. At least one of id or buyeruid is
recommended.
buyeruid
string; recommended
Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyeruid or id is recommended.
yob
integer
Year of birth as a 4-digit integer.
gender
string
Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
keywords
string
Comma separated list of keywords, interests, or intent.
customdata
string
Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks.
geo
object
Location of the user’s home base defined by a Geo object. This is not necessarily their current location.
data
object array
Additional user data. Each Data object represents a different data source.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
App
Attribute
Type
Description
id
string; recommended
Exchange-specific app ID.
name
string
App name (may be aliased at the publisher’s request).
bundle
string; required
A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID.
domain
string
storeurl
string
App store URL for an installed app; for IQG 2.1 compliance.
cat
string array; recommended
Array of IAB content categories of the app.
sectioncat
string array
Array of IAB content categories that describe the current section of the app.
pagecat
string array
Array of IAB content categories that describe the current page or view of the app.
ver
string
Application version.
privacypolicy
integer
Indicates if the app has a privacy policy, where 0 = no, 1 = yes.
paid
integer
0 = app is free, 1 = the app is a paid version.
publisher
object
Details about the Publisher of the app.
content
object
Details about the Content within the app.
keywords
string
Comma separated list of keywords about the app.
ext
object
Placeholder for exchange-specific extensions to OpenRTB
Bid Response
DTXplatform expects to receive a Bid Response for each BidRequest. The following table describes the fields and objects in the BidResponse message. All calls should return HTTP code 200 except for an empty bid response (no bids) which should return HTTP code 204.
Attribute
Type
Description
id
string; required
ID of the bid request to which this is a response.
seatbid
object array
Array of seatbid objects; 1+ required if a bid is to be made.
bidid
string
Bidder generated response ID to assist with logging/tracking.
cur
string;
default “USD”
Bid currency using ISO-4217 alpha codes.
customdata
string
Optional feature to allow a bidder to set data in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks.
nbr
integer
Reason for not bidding.
ext
object
Placeholder for bidder-specific extensions to OpenRTB
Note: we recommend using field “cur”, even if you set USD as default currency, except cases when it is specified in the agreement.
Seat Bid
Attribute
Type
Description
bid
object array;
required
Array with 1 Bid object.
seat
string
ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made.
group
integer; default 0
0 = impressions can be won individually; 1 = impressions must be won or lost as a group.
ext
object
Placeholder for bidder-specific extensions to OpenRTB.
Bid
Attribute
Type
Description
id
string; required
Bidder generated bid ID to assist with logging/tracking.
impid
string; required
ID of the Imp object in the related bid request.
price
float; required
Bid price expressed as CPM although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java).
adid
string
ID of a preloaded ad to be served if the bid wins.
nurl
string
Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup.
adm
string
Optional means of conveying ad markup in case the bid wins;
supersedes the win notice if markup is included in both.
adomain
string array
This can be an array of for the case of rotating creatives.
Exchanges can mandate that only one domain is allowed.
bundle
string
A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID.
cid
string
Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
crid
string
Creative ID to assist with ad quality checking.
cat
string array
IAB content categories of the creative.
attr
integer array
Set of attributes describing the creative.
api
integer
API required by the markup if applicable.
protocol
integer
Video response protocol of the markup if applicable.
w
integer
Width of the creative in device independent pixels (DIPS).
h
integer
Height of the creative in device independent pixels (DIPS).
ext
object
Placeholder for bidder-specific extensions to OpenRTB
Substitution Macros
Any of the following substitution macros can be included in the Win Notice URL or Ad Markup. If present, they will each be replaced by the appropriate data.
If the suffix: B64 is appended to the macro name, the data will be Base64-encoded prior to the substitution.
For example, ${AUCTION_AD_ID:B64}.
Macro
Description
${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_AD_ID}
ID of the ad markup the bidder wishes to serve; from “adid” attribute.
${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.
Banner Bid Request Example
Native Bid Request Example
Video Bid Request Example
Site Pop Bid Request Example
App Push Notification Bid Request Example
Audio Bid request Example
Banner Bid Response Example
Native Bid Response Example
Video Bid Response Example (Linear VAST 2.0)
Site Pop Bid Response Example
App Push Notification Bid Response Example
Audio Bid Response Example
Last updated