Getting Started With OpenRTB

Home » Marketer Documentation » 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

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 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 &) 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, 4.1, 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 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

Smaato supports first-price auctions.

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.

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, Preferred 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

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

Last Modified: August 31, 2023 at 11:53 am