ℹ️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 | Block list of advertisers by their domains (e.g., “http://ford.com ”). |
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 | Domain of the site (e.g., “http://mysite.foo.com ”). |
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 | Domain of the app (e.g., “http://mygame.foo.com ”). |
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 | Advertiser domain for block list checking (e.g., “http://ford.com ”). 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