Getting Started With OpenRTB

Nexus supports integrations based on the IAB Tech Lab OpenRTB 2.6, OpenRTB 2.5, and OpenRTB 2.4 specifications, with the Nexus-specific requirements documented below.

Recommended version: New integrations should use OpenRTB 2.6. OpenRTB 2.4 and 2.5 remain documented for backward compatibility.

• Nexus-specific: XML ad markup in adm uses the Nexus schema shown in this guide. Buyers must adapt their markup accordingly.
• Nexus only allows ad markups as part of the bid response. We do not support ad markup responses at the win notice. You can utilize both HTML and XML ad markup inside the bid response.
• Demand partners can configure their entire ad markup in XML. Nexus requires the “width” and “height” parameter inside of the bid object for XML ads to ensure bid requests and response sizes are matched.
• Bid prices are expressed as CPM in USD. Use cur: ["USD"] in requests and cur: "USD" in responses where applicable.
• The buyer must provide a valid HTTPS bidding endpoint. The endpoint may contain pre-agreed query parameters and must accept bid requests via HTTP POST.
• Number of bids per request:
  • For Image Display, Rich Media , Video and Popunder Ads - one bid per request only (One impression object)
  • For Native Ads - multiple bids per request are supported

Supported Ad Formats

• Image Display Ads
• Rich Media Ads
• Native Ads
• Video Ads
• Popunder Ads

Bid Request Headers

• x-openrtb-version: 2.6 for OpenRTB 2.6 requests; use 2.5 or 2.4 only for legacy integrations.
• Content-Type: application/json; charset=utf-8
• Content-Encoding: gzip when the request body is compressed.
• Accept-Encoding: gzip indicates that Nexus can accept a compressed bid response.

CDATA/Escaping for XML Ad Markups

When bidding with a rich media ad, we suggest putting the content of all XML tags (e.g.<content>, <beacon>, <clickURL>, <imgUrl>, etc.) in a CDATA construct. CDATA in XML requires no encoding whatsoever. Passing an XML document in a JSON-context, however, needs JSON syntax and escaping rules to be applied, as follows:

• All double quotes are escaped as \”.
• Apostrophes are not to be escaped.
• The XML doc is to be stripped of all tab and newline characters (this is actually important).
• Make sure that XML characters (like &, <, >) in URLs inside of the <beacons>, <imgUrl/> and <clickUrl/> sections are either HTML escaped (e.g. replace & with &) if not in a CDATA construct.

Please Note: Ad markups cannot contain full HTML pages. Document declaration tags like DOCTYPE, HTML, head, body, etc. are not supported and can cause issues with rendering.

ADM Examples

Image Display Ads: XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
    <imageAd>
        <clickUrl><![CDATA[https://www.example.com]]></clickUrl>
        <imgUrl><![CDATA[https://www.example.com/images.jpg]]></imgUrl>
        <width>320</width>
        <height>50</height>
    </imageAd>
</ad>

Rich Media Ads: XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
    <richmediaAd>
        <content><![CDATA[   HTML/JS CODE   ]]></content>
        <width>320</width>
        <height>50</height>
    </richmediaAd>
</ad>

Popunder Ads: XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
    <popunderAd>
        <clickUrl><![CDATA[https://www.example.com]]></clickUrl>
    </popunderAd>
</ad>

Video

• We support instream video (pre-roll/mid-roll/post-roll), interstitial video, outstream video, rewarded video. The supported formats are VAST 2.0, 3.0, 4.0, and VPAID 2.0. VPAID is only supported in JS format.
• OpenRTB 2.5 video request and response examples
• OpenRTB 2.4 video request and response examples

Native

• Nexus supports the Native 1.1 and 1.2 examples documented here. The native response in adm must be a JSON-encoded string.
• OpenRTB 2.5 Native 1.1 and 1.2 examples
• OpenRTB 2.4 Native 1.1 and 1.2 examples

SSL Support

Nexus expects all buyers to honor imp.secure. When imp.secure: 1, every creative, media, click, and tracking URL returned by the buyer must use HTTPS.

Impression Counting and Win Notifications

Nexus-specific billing policy: Nexus records a billable impression only after its impression beacon confirms that the ad was displayed. Buyers must provide nurl in each bid response for Nexus win-notification processing.

IAB distinction: An OpenRTB nurl is a win notice and, by itself, does not prove that an ad was delivered, viewed, or billable. Do not count standard win notices as impressions unless your Nexus integration agreement explicitly requires that behavior. OpenRTB 2.5 integrations may also use burl for billing notices where agreed.

Bid Request/Response Compression

Nexus requires all new partners to accept GZIP-compressed bid requests. Nexus also accepts compressed bid responses when the request includes Accept-Encoding: gzip. See GZIP Compression.

Bid Response Duration

The allowed request duration for each auction is indicated in the top-level tmax field in the bid request. Any response received after that timeframe will be ignored. The default setting for request duration is 300 ms (round trip) but there are many requests that are lower. We recommend our partners’ response time be below 100 ms in order to have access to latency-sensitive inventory.

No Bid Response

• To answer to a bid request without making an actual bid, an HTTP response code 204 "No Content" should be sent.
• No-bid reason codes sent by Nexus follow the OpenRTB 2.5 specification, section 5.24.
  • To receive a No Bid Reason, you need to support the nbr field in bid responses
  • To enable No Bid Reasons on your Nexus account, contact your Account Manager