RTB Protocol

This article presents the heart of the Marketplace API and the Real-Time Bidding protocol.

Ad requests originate at publisher sites; both mobile web and mobile applications. The majority of mobile web requests originate from publishers’ servers rather than browsers; a very common characteristic of the mobile advertising ecosystem. For each inbound request to the Marketplace, bid requests are broadcast to interested bidders, responses are evaluated, the winner is notified, and ad markup is served. The most common form of this interaction is shown in the figure below, but there are variations available to accommodate the needs of different bidders.

Transport

RTBProtocol_bidFlow.PNG

Transport pertains to the communications channel between the Marketplace and bidders. ONE by AOL: Mobile is configured in the following way:

  • The ONE by AOL: Mobile Marketplace sends bid requests via HTTP POST. SSL is not supported. 
  • Multiple ad servers attempt to establish persistent HTTP connections to each bidder.
  • HTTP Keep-Alive must be supported.

 

Protocol

Below is ONE by AOL: Mobile’s implementation of the OpenRTB 2.3 spec. Protocol pertains to the actual auction conversation between the Marketplace and bidders as well as the mechanism for serving the winning ad.

Bid Request

Attribute Usage Additional Information and Nexage Specific Comments
BidRequest    
id Supported  
at Supported Although optional, always included on ONE by AOL: Mobile RTB bid requests. Value "1" indicates First Price auctions,  Value "2" defines Second Price Plus. Most auctions are Second Price Plus.
tmax Not Supported Set at exchange level - therefore not passed in requests
wseat Not Supported  
allimps Not Supported  
cur Not Supported Always USD
bcat Supported May be suppressed. ONE by AOL: Mobile uses custom categories in addition to the standard IAB advertising categories. Please see ONE by AOL: Mobile Custom Categories for a full list.
badv Supported May be suppressed
test Not Supported  
ext -- Currently no extensions
Imp    
id Supported  
displaymanager Supported  
displaymanagerver Supported  
instl Supported  
tagid Supported  
bidfloorcur Not Supported  
iframebuster Not Supported  
secure Supported  
ext -- Nexage custom attributes:
  nex_sd Supported Session depth (i.e., n'th ad of this user session; 0 = greater than 10).
  nex_cpi Supported CPI tracking strings:  { "cts": "string", "dids": "string" } Allow bids: 0 = without restriction, 1 = that have "adomain" AND "iurl", 2 = "adomain", 3 = "iurl";
  nex_screen Supported 4 = "adomain" OR "iurl".  Options 1-4 also require "cid".
Banner    
v Not Supported  
h Supported  
w Supported  
hmin Not Supported  
wmin Not Supported  
hmax Not Supported  
wmax Not Supported  
pos Supported  
battr Supported  
btype Supported  
mimes Not Supported  
topframe Not Supported  
expdir Not Supported  
api Supported  
ext -- Currently no extensions
Video    
h Supported  
w Supported  
pos Supported  
battr Supported  
mimes Supported  
linearity Supported  
minduration Supported  
maxduration Supported  
protocol Supported Scheduled for deprecation in upcoming OpenRTB version.
protocols Supported  
startdelay Supported  
sequence Not Supported  
maxextended Not Supported  
minbitrate Not Supported  
maxbitrate Supported  
boxingallowed Not Supported  
playbackmethod Supported  
delivery Not Supported  
companionad Not Supported  
api Supported  
ext -- Nexage custom attributes:
  skippable Supported Used to communicate mandatory skippability
  skipthreshold Supported Video length skip threshold for mandatory skippable video ads
  skipoffset Supported Time when the skip button appears
 maxbitrate Supported  
Native    
request Supported  
ver Supported  
api Supported Where VPAID requests are communicated
battr Not Supported  
ext -- Currently no extensions
Site    
id Supported May be aliased
name Supported May be aliased or suppressed
domain Supported May be suppressed
cat Supported  
sectioncat Not Supported  
pagecat Not Supported  
keywords Supported  
mobile Supported Always set to "1" in ONE by AOL: Mobile
page Supported May be suppressed
ref Supported May be suppressed
search Supported  
privacypolicy Not Supported  
ext -- Nexage custom attributes:
   imp.hb Supported 0 or 1 Indicator if bid is for header bidding
App    
id Supported May be aliased
name Supported May be aliased or suppressed
domain Supported May be suppressed
cat Supported  
sectioncat Not Supported  
pagecat Not Supported  
keywords Supported  
ver Not Supported  
bundle Supported  
paid Not Supported  
storeurl Supported  
privacypolicy Not Supported  
Publisher    
id Supported May be aliased
name Supported May be aliased or suppressed
domain Not Supported  
cat Not Supported  
ext -- Nexage custom attributes:
  nex_else Supported For bidders with expanded Data contracts
Content    
id Not Supported  
episode Not Supported  
title Not Supported  
series Not Supported  
season Not Supported  
url Not Supported  
cat Not Supported  
videoquality Not Supported  
keywords Not Supported  
contentrating Not Supported  
userrating Not Supported  
context Not Supported  
livestream Not Supported  
sourcerelationship Not Supported  
len Not Supported  
qagmediarating Not Supported  
embeddable Not Supported  
language Not Supported  
ext -- Currently no extensions
Producer    
id Not Supported  
name Not Supported  
domain Not Supported  
cat Not Supported  
ext -- Currently no extensions
Device    
ua Supported  
ip Supported  
ipv6 Not Supported  
dnt Supported Available for iOS 6+ only; 0/1 value is negated from the iOS setting.
lmt Supported Same as dnt
ifa Supported  
didsha1 Supported  
didmd5 Supported  
dpidsha1 Supported  
dpidmd5 Supported  
macsha1 Supported  
macmd5 Supported  
carrier Supported  
make Supported  
model Supported  
os Supported  
osv Supported  
js Supported  
language Supported  
h Not Supported  
w Not Supported  
pxratio Not Supported  
ppi Supported  
hwv Supported  
connectiontype Supported  
devicetype Supported  
flashver Not Supported  
ext -- Nexage custom attributes:
 nex_ifasha1 Supported iOS Advertiser ID hashed as SHA1.
 nex_ifamd5 Supported iOS Advertiser ID hashed as MD5
Geo    
lat Supported Supported when device location services are enabled
lon Supported Supported when device location services are enabled
country Supported  
city Supported  
zip Supported  
metro Supported Supported when device location services are enabled
region Supported Supported for USA states only; only the region part of the ISO-3116-2 codes are included
regionfips104 Not Supported  
utcoffset Not Supported  
type Supported Hard coded for User.Geo objects
ext -- Currently no extensions
User    
id Supported  
buyeruid Supported  
yob Supported  
gender Supported  
keywords Supported  
customdata Not Supported  
ext -- Nexage custom attributes:
  nex_eth Supported Ethnicity as "0" (African-American), "1" (Asian), "2" (Hispanic), "3" (White), or "4" (Other)
  nex_marital Supported Case sensitive marital status as "S", "M", "D", or "O" for single, married, divorced, or other.
  nex_kids Supported Case sensitive indicator of any kids within the household as "Y" or "N" for yes or no.
  nex_hhi Supported Household income in local base units (e.g., Dollars, Euros, yen) annually.
  nex_dma Supported Designated Market Area (DMA) by Nielsen Media Research of the consumer's home base.
Data    
id Not Supported  
name Not Supported  
segment Not Supported  
ext -- Currently no extensions
Segment    
id Not Supported  
name Not Supported  
value Not Supported  
ext -- Currently no extensions
Regs    
coppa Supported  
ext -- Currently no extensions
Pmp    
private_auction Not Supported Omitted by design because PMP's may contain both public and private deals.
deals Supported  
ext -- Currently no extensions
Deal    
id Supported  
at Supported  
bidfloor Supported  
bidfloorcur Not Supported Assumed to be "USD"
wseat Supported  
wadomain Supported  
ext -- Currently no extensions

Bid Response

ONE by AOL: Mobile RTB bid requests will always carry a single impression, whereas the OpenRTB schema allows for impression bundles.

Attribute Usage Additional Information and Nexage Specific Comments
BidResponse    
bidid Supported  
cur Not Supported Always assumed USD ($)
customdata Not Supported  
nbr Supported Although supported, the preferred way to communicate a no-bid response is an empty Ad Response.
ext -- Currently no extensions
SeatBid    
seat Supported ONE by AOL: Mobile recommends the use of multiple bids using the "seatbid" object to increase the likelihood of winning the auction. In cases where ONE by AOL: Mobile targeting, blocklists, or Ad Screening may cause a winning bid to not be served, additional bids are considered independently and could ultimately win the auction.
group Not Supported AOL Mobile only includes a single impression per bid request
ext -- Currently no extensions
Bid    
id Not Supported  
impid Supported  
dealid Supported  
price Supported Maximum precision of 8 digits to the right of the decimal point (e.g., 12.12345678). The maximum "price" is $1,000 CPM. Bids with higher pricing will be considered $1,000 CPM
adid Supported  
nurl Supported Default win notice URL can also be set in the bidder's configuration. If nurl is omitted, default is used
adm Supported Required if nurl is omitted and the bidder's configuration does not include a default win notice URL. Note: if an auction winner fails to return ad markup via the “adm” or win notice response, then the win will be forfeited and the Marketplace will select a new winner.
cid Supported Required if BidRequest.Imp.nex_screen = "1", "2", "3", or "4
crid Supported  
iurl Supported Required if BidRequest.Imp.nex_screen = "1", "3", or "4" if adomain is omitted
adomain Supported Required if BidRequest.Imp.nex_screen = "1", "2", or "4" if iurl is omitted
attr Not Supported  
cat Not Supported  
bundle Not Supported  
h Not Supported  
w Not Supported  
ext -- Nexage custom attributes:
   burl Supported Billing Notification URL, fired when we have confirmed that a creative has been delivered to a device, which is what ONE by AOL: Mobile considers the billable event. All of the existing win notice url macros are available.

For information on video bid responses see Mobile Video Specs and SSL Requirements for Buyers.

If you require information on how ONE by AOL: Mobile has implemented any other versions of the OpenRTB spec, please reach out to your Demand Services Manager.

Have more questions? Submit a request