OpenRTB

Introduction  

The Display.io OpenRTB API specification allows publishers, interested in buying from our marketplaces, to integrate directly with Display.io. This document lays out general characteristics and requirements, Ad request and Ad response structures to enable publishers to integrate correctly with Display.io. 

Endpoint URL

Please, approach your account manager in order to get endpoint URL.

Protocol

OpenRTB Specification Version 2.5.

Note: Placement ID is a mandatory parameter and must be defined within Ad Request: 

• Option 1: Endpoint URL (parameter: ‘placement’) 
• Option 2: OpenRTB parameter tagid (Object: Imp)

Note: Only one object ‘banner’ or ‘video’ must be sent inside ‘imp’ object within Ad Request.

Other specific requirements in addition to OpenRTB-2.5 are defined below.

Bid Request Method   

Bid Requests must be sent using the POST method over HTTP (or secured) protocol.

Required headers

Content-Type: application/json
User-Agent: server user agent

Notes for Bid Response

Markup is provided within ‘adm’ parameter.
Impression beacons are provided inside ‘ext.imptrackers’ parameter for display bids, and inside VAST for video bids.
Impression beacons may contain ${AUCTION_PRICE} macros, which must be replaced by a publisher with an actual clearing price.

Testing Mode

There are 2 options to apply a test mode for integration testing:

• Define status Testing for Placements on Publisher Portal.
• Send test parameter within Ad Request (request.test, string):
• "test":"1" - test mode,
• "test":"0" or missing - live mode. 
  
  

Data Center Location

US-EAST

Ad Request Parameters

Ad Request Example:

{
    "id": "",
    "imp": [
        {
            "id": "1",
            "video": {
                "w": 640,
                "h": 360,
                "pos": 3,
                "protocols": [
                    2,
                    3,
                ],
                "mimes": [
                    "video/mp4"
                ],
                "minduration": 4,
                "maxduration": 30,
                "battr": [
                    8,
                    17,
                    10,
                    9
                ],
                "linearity": 1,
                "minbitrate": 250,
                "maxbitrate": 10000,
                "api": [
                    7
                ]
            },
            "displaymanager": "display.io",
            "displaymanagerver": "1.0.0",
            "instl": 1,
            "tagid": "5237",
            "bidfloor": 1.53
        }
    ],
    "app": {
        "id": "7727",
        "name": "demo_app",
        "cat": [
            "IAB9-30"
        ],
        "bundle": "359917414",
        "publisher": {
            "id": "2",
            "name": "demo_publisher"
        },
        "storeurl": "https://apps.apple.com/us/app/word-wiz-connect-words-game/id1462123372"
    },
    "device": {
        "dnt": 0,
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
        "ip": "194.183.182.60",
        "geo": {
            "lat": 31.848,
            "lon": -81.602,
            "ipservice": 3,
            "country": "",
            "region": "",
            "city": "",
            "zip": "",
            "type": 2
        },
        "carrier": "311-480",
        "make": "Apple",
        "model": "iPhone 8 Plus (Verizon/Sprint/China/A1864)",
        "os": "iOS",
        "osv": "13.2",
        "js": 0,
        "connectiontype": 2,
        "devicetype": 1,
        "ifa": "CB00CEE0-70B3-485A-BB0B-2DF3F9C50499",
        "lmt": 0,
        "h": 2208,
        "w": 1242
    },
    "user": {
        "ext": {
            "consent": "",
        }
    },
    "at": 1,
    "badv": [],
    "source": {
         "omidpn": "SomeTest",
         "omidpv": "4.0.0"
        }
    },
    "bcat": [
        "IAB25",
        "IAB26",
        "IAB7-39"
    ],
    "regs": {
        "coppa": 0,
        "ext": {
            "gdpr": 0
        }
    }
}

Ad Response Example:

{
    "id": "5e54f7312b91d",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "9",
                    "impid": "5e54f73141ac8",
                    "price": 10.098,
                    "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"3.0\"><Ad><InLine><AdSystem>Display.io</AdSystem><AdTitle>446787759</AdTitle><Impression id=\"0\"><![CDATA[http://appsrv.displayio.loc/imp?msessId=5e54f731409d2&tls=20033339_28_14&p=6&winPrice=${AUCTION_PRICE}&XDEBUG_SESSION_START=netbeans-xdebug]]></Impression><Creatives><Creative><Linear><Duration>00:00:06</Duration><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" bitrate=\"399\" width=\"640\" height=\"360\" scalable=\"false\" maintainAspectRatio=\"false\">https://gcdn.2mdn.net/videoplayback/id/6063430121e17647/itag/18/source/doubleclick_dmm/ctier/L/acao/yes/ip/0.0.0.0/ipbits/0/expire/3706554999/sparams/id,itag,source,ctier,acao,ip,ipbits,expire/signature/78F2C6CDEA6C12EA7E3FC2FABF4B966950C81956.B082E8D1E2289BB9BF15B6F2867B1F817274A8B0/key/ck2/file/file.mp4</MediaFile></MediaFiles><VideoClicks><ClickThrough>https://adclick.g.doubleclick.net/pcs/click?xai=AKAOjssl485wLM2wPo4x4rLWmGT-WknFO4tklBnasvtXyirOqCA_-WmjaPTZVXHNEtRRX7WqDEll-J848oUO4Z9pvOXjcMwaBqQUKZOb&sig=Cg0ArKJSzAiK-DNkVU5NEAE&urlfix=1&adurl=https://apiservices.krxd.net/click_tracker/track%3Fkxconfid%3Dsqwlj2m1i%26kxcampaignid%3D22864588%26kxadvertiserid%3D3340030%26kxplacementid%3D250302115%26kxadid%3D446787759%26kxcreativeid%3D118480275%26kxsiteid%3D1441253%26kxbrand%3DClorox%26clk%3Dhttps%253A%252F%252Fwww.clorox.com%252Four-purpose%252Fclean-spaces%252F%253Futm_medium%253Dpaid-media%2526utm_campaign%253DBTS%2BFY20%2BClorox%2BBack%2Bto%2BSchool%2B-%2BDSP%2BVideo%2B%2526utm_content%253D250302115%2526utm_term%253D118480275%2526utm_source%253DN7088.3159.BIDMANAGER</ClickThrough></VideoClicks><TrackingEvents><Tracking event=\"start\"><![CDATA[Array]]></Tracking></TrackingEvents></Linear></Creative></Creatives></InLine></Ad></VAST>\n"
                }
            ]
        }
    ]
}

No Bid Response

HTTP 204 “No Content”