Getting Started With OpenRTB

DSP Onboarding Guide

Smaato supports the integration specifications for OpenRTB 2.2, 2.4, or 2.5.

OpenRTB 2.2

OpenRTB 2.4

OpenRTB 2.5

We have also provided example requests and responses to make it easier for you to understand the integration and auction process. Please refer to the specific OpenRTB version page and formats.

Introduction to OpenRTB

(From the IAB OpenRTB API Specifications Version 2.5) 

The first goal was to standardize communication between parties for exchanging block lists. Version 1.0 of the OpenRTB block list specification was released in December 2010. Due to very widespread adoption by the industry, OpenRTB was adopted as an IAB standard in January 2012 with the release of version 2.1. Governance over the technical content of the specification remains with the OpenRTB community and its governance rules.

The following figure illustrates the OpenRTB interactions between an exchange and its bidders. Ad requests originate at publisher sites or applications. For each inbound ad request, bid requests are broadcast to bidders, responses are evaluated under prevailing auction rules, and a winner is selected. The winning bidder is notified of the auction win via a win notice. Ad markup can either be included in the bid prospectively or in response to the win notice.

A separate billing notice is also available to accommodate varying policies enacted by exchanges that are beyond the scope of the OpenRTB specification (e.g., billing on device delivery, viewability, etc.). The win notice informs the bidder’s pricing algorithms of a success, whereas the billing notice indicates that spend should actually be applied. A loss notification is also available to inform the bidder of the reason their bid did not win.

The URLs for win, billing, and loss notices and the ad markup itself can contain any of several standard macros that enable the exchange to communicate critical data to the bidder (e.g., clearing price).

Supported Ad Formats

Ad Format Type Ad Formats
Image
  • Rich Media
  • MRAID V1 & V2
  • Non-MRAID
Video
  • Pre-/Mid-/Post-Roll Video
  • Interstitial Video
  • Outstream Video
  • Rewarded Video
  • VAST 2.0, 3.0, 4.0
  • VPAID 2.0
Native

Ad Markup Standard for Image and Rich Media Inventory

Smaato 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.

HTML Ad Markup

Demand partners can configure their entire ad markup in HTML. Smaato requires the “w” and “h” parameter inside of the bid object for HTML ads to ensure bid requests and response sizes are matched.

You can find an HTML ad markup sample:

{
    "id": "fd891d01-72fd-4e9c-8e90-a6d60f56bd24",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "BidId",
                    "impid": "1",
                    "price": 0.27,
                    "api": 3,
                    "adomain": [
                        "www.example.com"
                    ],
                    "crid": "365921",
                    "cid": "151015",
                    "nurl": "http://dsp.com/win?id=fd891d01-72fd-4e9c-8e90-a6d60f56bd24&impid=1&price=${AUCTION_PRICE}&rtb_id=86&cver=1&cam_id=151015&campaign_type=1&bid_time=1533557986832318",
                    "iurl": "https://dsp.com/creative/1124be69-b9bc-4c7d-8661-0c2f4c8a8a53.jpg",
                    "adm": "<div><a href=\"landingpage.com\"><img scr=\"https://cdn.dsp123.com/ad.jpg\" /></a>"
                }
            ]
        }
    ]
}

XML Ad Markup

The ad markup must be compliant with Smaato’s RTB ad markup XML standard as defined in the XML schema document. Demand partners must comply with ad markup standards of rich media and image ads.

  • XML Ad Markup For an XML ad markup spec and example click here
  • You can also download the XSD schema here.

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 &amp;) if not in a CDATA construct.

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.
  • For example video ad requests and responses for OpenRTB 2.5, click here

Native

  • Smaato follows the OpenRTB Native 1.1 spec. The ad markup should be configured as a JSON encoded string.
  • For example native ad requests and responses for OpenRTB 2.5, click here.

Bid Response Duration

The allowed request duration for each auction is indicated in the ext.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.

SSL Support

Smaato expects all buyers to be compliant with the secure field in the bid request. Demand partners should return secure creative markup assets when “imp.secure”:1

Endpoint Configuration

Smaato has data centers in US-EAST (Virginia, US), EMEA (Ireland), APAC (Singapore), and CHINA (Beijing). We require all buyers to provide regional endpoints for the markets they would like to buy media from.

Ad Quality Controls

For ad quality purposes, we require our demand partners to provide the following information in bid responses:

  • Advertiser Domain (adomain)
  • Campaign ID (cid)
  • Creative ID (crid)
  • Creative Attributes (attr)
  • API framework (api)

Impression Counting and Win Notifications

Smaato only charges its buyers when the Smaato impression beacon fires. This happens when an ad container is presented to a user. In other words, you will only be billed when Smaato verifies the impression and the ad is displayed. The win notification will be fired from Smaato servers right after the ad is viewed. We highly recommend all buyers to record impressions based on win notifications.

Auction Types

At Smaato we offer our buyers open auctions and open deals, as well as private marketplace preferred deals and private exchange deals.

Open Auctions

All current Smaato open auctions utilize OpenRTB at 2 parameters. The winning bidder only pays the second-highest price in the auction. Smaato is planning to support first-price auctions in the future.

Open Deals

Buyers can package Smaato inventory via Smaato’s self-service portal (SDX) and assigning a specific deal ID and seat ID to it.  Open Deals work in a similar fashion as Open Auctions, as they also utilize the second-price price auction model.

Preferred Deals (PMP)

Only one DSP is included in the auction.  The publisher creates a Deal ID and sets or negotiates a rate that the DSP can accept (by submitting a valid bid response) or decline (by not submitting a valid bid response) on an impression-by-impression basis. DSPs should bid and pay the price that was communicated in the bid request.

Private Exchange (PMP)

Private exchanges are a closed-exchange setup where only a limited amount of DSPs (up to 25) can bid on a publisher’s inventory. The Bid Floor and Deal ID are passed in the bid request. The DSP with the highest bid wins the auction and pays the second-highest price.

You can find the example private marketplace (PMP) requests and responses for OpenRTB 2.5 here.

Smaato Test Account

After the credit, contract, and tech questionnaire are completed, Smaato will create a test account for a new buyer. Testing contains two stages: the Bid Response Compliance Stage and the Traffic Validation Stage.

Bid Response Compliance Stage

The purpose of this stage is to validate the demand partner’s responses for all eligible ad types and buying methods (OpenRTB, Prefered Deal, Private Exchange).

    • Smaato creates specific app.ids for each ad type and auction type.
    • The demand partner needs to set up test campaigns for each ad type and buying method and whitelist them appropriately for each test campaign. The demand partner can choose to target app.id, imp.tagid or app.bundle.
    • The demand partner confirms that test campaigns are set.
    • Smaato will start sending requests manually from the demo application. Only a handful of requests will be sent so please adjust the fill rate of the test campaigns accordingly.
    • Smaato will verify the responses, ad rendering, and impression tracking beacons.
    • If all the above conditions are met, the demand partner will move to the traffic validation stage.

Traffic Validation Stage

The purpose of this stage is to ensure that there are no discrepancies in ad requests, impressions, and revenue.

    • Smaato sends live traffic with low QPS.
    • The demand partner begins bidding on live Smaato auctions.
    • The demand partner is expected to spend no more than $50/day and $150/test.
    • By analyzing the daily numbers, Smaato requires a less than 5% impression discrepancy and less than a 1% revenue discrepancy. If the above conditions are met, the demand partner will go live.

Bid Request/Response Compression

Smaato requires all new partners to allow GZIP compressed bid requests. We also accept GZIP compressed bid responses. For more information about GZIP, click here.

Bid Request Specification

(From the OpenRTB Specifications)

RTB transactions are initiated when an exchange or other supply source sends a bid request to a bidder. The bid request consists of the top-level bid request object, at least one impression object, and may optionally include additional objects providing impression context.

Object Model

The object model shown below, details the bid request decision process. The top-level object (i.e., in JSON the unnamed outer object) is denoted as BidRequest in the model. Of its direct subordinates, only Imp is technically required since it is fundamental to describing the impression being sold and it requires at least one of Banner (which may allow multiple formats), Video, Audio, and Native to define the type of impression (i.e., whichever one or more the publisher is willing to accept; although a bid will be for exactly one of those specified). An impression can optionally be subject to a private marketplace.

Further information about OpenRTB can be found here in the Developer Documentation under OpenRTB Integration and/or the example requests and response pages.  

OpenRTB 2.2

OpenRTB 2.4

OpenRTB 2.5

Modified: September 30, 2019 at 2:52 pm