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 vast 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

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: MobileMarketplace 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.

Representation

Representation addresses the format or schema of bid request and response messages. The default JSON format required. No other extended formats are supported at this time.

Protocol

Protocol pertains to the actual auction conversation between the Marketplace and bidders as well as the mechanism for serving the winning ad.

Bid Request

  • The maximum auction time “tmax” is not passed. The current maximum auction time is 200ms, though AOL reserves the right to change this at any time.
  • The auction type “at” is optional, but is always included on ONE by AOL: Mobile RTB bid requests. Value “1” indicates First Price auctions, Value “2” defines Second Price Plus. Currrently most auctions are Second Price Plus.
  • Fixed price auctions are supported for PMPs/Deals. An eligible bid at or above the fixed price will result in a win – regardless of the amount of any open market bids. 
  • Width and height parameters specify the ad slot size.  Ads served into ad slots should be an exact fit to the dimensions provided.
  • ONE by AOL: Mobile RTB bid requests will always carry a single impression, whereas the OpenRTB schema allows for impression bundles.
  • The ONE by AOL: Mobile Marketplace supports the concept of multiple seats per bidder.  However, the seat white list “wseat” array is not used.

Bid Response

  • The currency attribute “cur” is ignored since ONE by AOL: Mobile supports only USD. 
  • As of OpenRTB 2.0, only CPM bid units are supported.
  • The ONE by AOL: Mobile Marketplace supports the concept of multiple seats per bidder. When no seats are specified a default seat (i.e., the bidder itself) is used to align with OpenRTB. Bids are within the structure of the “seatbid” array. 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 would be considered independently and could ultimately win the auction.
  • Within the “seatbid” object to increase the likelyhood 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.
  • Within the “seatbid” object, the “group” attribute is ignored since this pertains to bid requests with multiple bundled impressions, which is not supported.
  • The preferred way to communicate a no-bid response is with an empty Ad Response (response with no body).
  • The ONE by AOL: Mobile Marketplace treats the bid array as optional. However, a bid response is only considered to carry a bid if a bid object exists and carries a “price” > 0.  Other cases (e.g., totally empty response, no “seatbid” array or object, no “bid” array or object, no “bid” objects with a “price” > 0) are all treated as no-bid.
  • If multiple bids are included, the ONE by AOL: Mobile Marketplace considers each bid response as an independent bid.
  • The “price” attribute within “bid” objects is evaluated to a maximum precision of 8 digits to the right of the decimal point (e.g., 12.12345678).
  • The maximum “price” is $1,000 CPM. Bids higher than that will be considered $1,000 CPM.

Win Notice & Substitution Macros

  • OpenRTB is fully supported with respect to the win notice and ad serving mechanisms.  In addition, a default win notice can be configured on the ONE by AOL: Mobile Marketplace.  This default win notice will be used if it is not passed via the “nurl” attribute.
  • All substitution macros are supported both in ad markup and in win notices (whether passed in the bid response or configured by default). No macro encoding options are supported.
  • Bidders can provide ad markup in their bid requests via the “adm” attribute in case they win or on the win notice response when they win. Only one method should be used in a given auction, but if non-empty strings are found in both, ONE by AOL: Mobile will use the bid response “adm” attribute and ignore the win notice return body.
  • On a given auction if the winning bidder fails to return ad markup via one of these two

Attribution

This layer specifies the business attributes that are added to the bid requests and responses defined in Protocol.

Bid Request

The objects “Site”, “App”, “Publisher”, “Device”, “User”, Banner”, “Video”, “Native”, “Pmp”, and “Deal” are supported. The objects “content” and “producer” are not supported. However, there are certain unsupported optional attributes and other notes as listed below. Note that availability and frequency of supported attributes varies by site, device type, availability of user data, and other factors. ONE by AOL: Mobile strives to provide as much data as possible to aid in good bidding decisions.

  • In the “site” object, at the publisher’s request, site name (i.e., “name”) may be transparent, replaced by aliases, or suppressed. Also at the publisher’s request, the site’s domain may be suppressed, which may also result in suppression of other attributes that include it (e.g., referring page “ref”). AOL encourages its publishers to be fully transparent.
  • Also, the "site" object now supports the OpenRTB 2.3 "mobile" attribute, always set to "1" in the ONE by AOL: Mobile.
  • In the “app” object, all attributes are supported except “sectioncat”, “pagecat”, application version “ver”, the paid application flag “paid”, and the privacy policy flag “privacypolicy”. As with the “site” object, the “name" attribute may be replaced by aliases or suppressed along with “domain” at the publisher’s request. Once again, AOL encourages its publishers to be fully transparent. The “bundle” attribute will include package name for Android apps (e.g., com.foo.mygame) and iTunes ID for iOS apps (e.g., 628677149).
  • The "nex_coppa" extension to the "site" and "app" objects is being deprecated. Instead, if it is known that COPPA does or does not apply, a "regs" object is added to the top level bid request with the "coppa" attribute set appropriately. If it is not known, a "regs" object is not included.
  • In the “publisher” object, “id” and “name” are supported.
  • In the “device” object, carrier is supported when a known mobile carrier is detected, and “WIFI” is passed when the user is identified as being on WiFi. Please see Mobile Carriers for a list of carrier strings passed in the bid request. Device “make”, “model”, operating system “os”, and operating system version “osv” are supported using values defined by DeviceAtlas. The “ip” attribute is supported as defined. Country is supported within the “device.geo” object. Attributes "ifa", "macsha1", "macmd5", "hwv" and "ppi" have been promoted from extensions to their OpenRTB 2.3 places directly on the "device" object. Similarly, the "nex_tablet" extension is being replaced by new values for the "devicetype" attribute as follows: 4 = phone, 5 = tablet, 1 = unknown. Finally, the "lmt" attribute is set to the same value as "dnt".
  • The “user” object is supported as defined, with several extensions as outlined below. 
  • Note that the advertiser domain block list (i.e., the “badv” attribute) may contain subdomains as well (e.g., “focus.ford.com” as well as “ford.com”), but not full URLs.
  • The "nex_secure" extension to the "imp" object is sent to OpenRTB 2.1 bidders 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. This is conveyed to OpenRTB 2.2+ bidders in the "imp.secure" attribute.
  • Related to the "banner" object, the "nex_mraid" extension is being replaced by new values for the "api" of the "banner" object as follows based on "mraid": 3 = MRAID-1, 5 = MRAID-2, or omit if unknown.
  • The “video” object is supported. ONE by AOL: Mobile only supports linear/in-stream VAST 3.0 video via this object. Also, any value in the "protocol" attribute is placed in the first array element of the OpenRTB 2.2 "protocols" attribute.
  • The “native” object is supported for OpenRTB 2.3 bidders who chose to receive Native 1.0 objects. Advertiser required native assets are not necessarily required by publishers to display.
  • For native requests “title”, “img”, and “data” objects are supported.
  • OpenRTB 2.2 and above bid requests may contain an auction type override of 3 in the PMP object corresponding to a fixed priced.
  • ONE by AOL: Mobile uses custom categories for categorization of advertising, in addition to the standard IAB categories. These categories will begin with “NEX” and are sent alongside the IAB categories in “bcat”. Please see ONE by AOL: Mobile Custom Categories for a full list of custom categories.
  • The floor for the auction, if applicable, is specified in "imp.bidfloor".

Bid Response

All bid response attributes are supported by ONE by AOL: Mobile. In particular, the following OpenRTB 2.2 and 2.3 attributes are included:

  • The "nbr" attribute on the top level bid response object
  • On the "bid" object, the "dealid", "h", "w", "cat", and "bundle" attributes
  • For native bid responses all required fields are supported. Optional Native fields such as publisher “required”  and “jstracker” are not supported. The following optional fields are supported:
    • imprtackers[] field is supported for the native object
    • “h” and “w” attributes are required on the “image” object within a native response object
  • For video bid responses, mime type of mp4 is required.
  • For video bid responses, bit rate is required. Allowable bit rates are 400-1200kbps for wifi and 400-800 for cellular.
  • For VAST Wrapper bid responses, the maximum number of jumps that will take place is 3, meaning a maximum 3 wrappers can be served before an inline ad is served.

 

Important Information about ONE by AOL: Mobile Ad Quality

Ad Screening - AOL provides publishers with the ability to review creatives running on their sites and applications through ONE by AOL: Mobile. Providing this type of visibility is important to enable high value publishers to sell their inventory on the Marketplace while maintaining control of their brand and eliminating channel conflict. By default, all buyers have access to any given publisher, but a publisher may opt to restrict access to their inventory for buyers who do not enable ad screening.

Ad Verification - In addition, ONE by AOL: Mobile verifies the advertiser domain and IAB Level-2 content category of all ads served via ONE by AOL: Mobile. For an ad to be “qualified” for Ad Verification, the Bid Response must include properly formatted “iurl”, “cid”, “crid” and “adomain”.

To enable Ad Screening and Ad Verification to ensure you are eligible to buy from the widest range of high value publishers, you must include in all “bid” objects the following attributes as defined:

"iurl"

  • “iurl” should be either the actual creative image or a representative image.
  • “iurl” should NOT be a link to an html page and should not be a generic placeholder image.
  • It's important that the “iurl” represent the campaign of which it's a part.
  • In the case of rich media, the “iurl” should be a static image that represents the actual creative that will be served.
  • “iurl” must be 256 characters or less.
  • “iurl” is required for native responses and should contain a url to a representative image of all native assets.
  • HTTPS must not be used for image URL values.

"cid"

  • Campaign id should be the value used by the bidder to track and organize their campaigns.
  • In many cases there will be multiple creative ids that roll up to each campaign.
  • “cid” must be 40 characters or less.

"crid"

  • Creative id should be the value used by the bidder to track and organize their creatives.
  • “crid” must be 40 characters or less.

"adomain"

  • “adomain” is the advertiser's domain. The “adomain” submitted by a bidder should reflect the main domain of the advertiser or product being advertised.
  • For apps, it should be the domain of the advertiser (e.g. advertiser.com), NOT a link to the App Store.
  • It should NOT be an ad server url or the domain of the bidder.
  • The “adomain” should ONLY include a subdomain if it is relevant and the subdomain is not "www". For example, the adomain should be advertiser.com not www.advertiser.com, butsubdomain.advertiser.com is preferred over advertiser.com, if relevant.
  • This should NOT include http:// or https://.
  • There should be NO paths in the “adomain” (e.g. advertiser.com/subdomain).
  • “adomain” must be 64 characters or less.
  • “adomain” is an array with one element, as ONE by AOL: Mobile only accepts one “adomain” value per bid. 

Extension

Extension enables an Exchange to support attributes in addition to those specified in Attribution. ONE by AOL: Mobile uses this mechanism to augment the “imp”, “banner”, “video”,  “site”, “app”, “content”,  “publisher”, “geo”, “user” and “device” objects in the bid request, as well as to enable bidders to send additional information on the bid response. These ONE by AOL: Mobile-specific extended attributes are defined as follows.

Publisher Object (“publisher”)

Field Type Default Description
ext.nex_else integer 0 Please consult your Demand Services Manager for more details.

Site Object ("site")

Field Type Default Description
ext.nex_data_proximic string -  

App Object ("app")

Field Type Default Description
ext.nex_sdkv string - The SDK version generating the ad request.

Impression Object ("imp")

Field Type Default Description
ext.nex_screen integer - Bid response requirements for this bid request, as specified in section 2.4.2 of the OpenRTB Mobile RTB API doc.  “0” for no requirements, “1” must contain cid,  adomain and iurl;, “2” must contain cid, and adomain, “3” must contain cid, and iurl, “4” must contain cid, and either adomain or iurl.  Bid responses not conforming to these requirements will be dropped.
ext.nex_sd integer - Session depth. For impressions 1-10 of a user’s session, this will be the actual depth.  After the 10th impression, this value will be “0”.
ext.nex_secure  integer - If the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown. 

User Object ("user")

<td">-
Field Type Default Description
ext.nex_eth string Ethnicity as “0” (African-American), “1” (Asian), “2” (Hispanic),“3” (White), or “4” (Other).
ext.nex_marital string - Marital status as “S” (single), “M” (married), “D” (divorced), or “O” other.
ext.nex_kids string - Indicator of kids in the household. “Y” or “N”.
ext.nex_dma string - DMA for the user.
ext.nex_hhi integer (10) - Household income in local base units (e.g., USD, Euros) annually.
ext.nex_prizm string - Nielsen PRIZM cluster. Contact AOL Demand Services for values.
ext.nex_targus string - TargusInfo AdAdvisor segment. Contact AOL Demand Services for values.
ext.nex_education string   Education level. “1” for high school, “2” for college, “3” for graduate school.
ext.nex_occupation string - Occupation.  Contact AOL Demand Services for values.

Bid Response

Bid Object ("bid")

Field Type Description
ext.burl string 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.

Please see SSL Requirements for Buyers.

Have more questions? Submit a request