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
Parameter |
Attribute |
Type |
Description |
Mandatory Parameters |
|||
imp |
tagid |
String |
Placement ID on Display.io platform (Publisher Portal). |
imp |
bidfloor |
Float |
Minimum bid for this impression expressed in CPM |
app |
id |
String |
Application ID on display.io platform (Publisher Portal). |
Required Parameters |
|||
app |
bundle |
String |
Application bundle or package name as provided in the App Store or Google Play Store. |
app |
name |
String |
Application name |
app |
cat |
String array |
Array of IAB content categories of the app. |
imp.banner |
h |
Integer |
Exact height in device independent pixels (DIPS)
|
imp.banner |
w |
Integer |
Exact width in device independent pixels (DIPS)
|
imp.banner |
pos |
Integer |
Ad position on screen. List of options is available in OpenRTB 2.5. Spec - 5.4 Ad Position: link |
imp.banner |
btype |
Integer array |
Blocked banner ad types. List of options is available in OpenRTB 2.5. Spec - 5.2 Banner Ad Types: link |
imp.banner |
battr |
Integer array |
Blocked creative attributes. List of options is available in OpenRTB 2.5. Spec - 5.3 Creative Attributes: link |
imp.banner |
api |
Integer array |
List of supported API frameworks for this impression
Note: 5 or 6 - mandatory, 7 - recommended. |
imp.video |
protocols |
Integer array |
Array of supported video protocols.
Full list of options is available in OpenRTB 2.5. Spec - 5.8 Protocols: link |
imp.video |
api |
Integer array |
Supported options: 7 - OMID-1 Full list of options is available in OpenRTB 2.5. Spec - 5.6 API Frameworks: link, OpenRTB Spec extension: link |
imp.video |
mimes |
String array |
Content MIME types supported (e.g., “video/x-ms-wmv”, “video/mp4”). |
imp.video |
minduration |
Integer |
Minimum video ad duration in seconds. |
imp.video |
maxduration |
Integer |
Maximum video ad duration in seconds. |
imp.video |
pos |
Integer |
Ad position on screen. List of options is available in OpenRTB 2.5. Spec - 5.4 Ad Position: link |
imp.video |
w |
Integer |
Width of the video player in device independent pixels (DIPS). |
imp.video |
h |
Integer |
Height of the video player in device independent pixels (DIPS). |
imp.video |
battr |
Integer array |
Blocked creative attributes. List of options is available in openRTB 2.5. Spec - 5.3 Creative Attributes: link |
imp.video |
linearity |
integer |
Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. List of options is available in OpenRTB 2.5. Spec - 5.7 Video Linearity: link |
imp.video |
minbitrate |
Integer |
Minimum bit rate in Kbps. |
imp.video |
maxbitrate |
Integer |
Maximum bit rate in Kbps. |
device |
ifa |
String |
Identifiers for Advertisers |
device |
ua |
String |
Browser user agent string. |
device |
ip |
String |
IPv4 address closest to device. |
device.geo |
lat |
Float |
Latitude from -90.0 to +90.0, where negative is south. |
device.geo |
lon |
Float |
Longitude from -180.0 to +180.0, where negative is west. |
device |
carrier |
String |
Carrier or ISP (e.g., “VERIZON”) using exchange curated string names which should be published to bidders a priori. |
device |
make |
String |
Device make (e.g., “Apple”). |
device |
model |
String |
Device model (e.g., “iPhone”). |
device |
os |
String |
Device operating system (e.g., “iOS”). |
device |
osv |
String |
Device operating system version (e.g., “3.1.2”). |
device |
connectiontype |
String |
Network connection type |
device |
devicetype |
String |
The general type of device. |
device |
h |
Integer |
Physical height of the screen in pixels. |
device |
w |
Integer |
Physical width of the screen in pixels |
badv |
- |
String Array |
Block list of advertisers by their domains (e.g., “ford.com”). |
bcat |
- |
String Array |
Display.io bcat list: |
sourse.ext |
omidvp |
String |
Identifier of the OM SDK integration. This is the same as the "name" parameter of the OMID Partner object. OpenRTB spec extension: link |
sourse.ext |
omidvn |
String |
Version of the OM SDK integration. This is the same as the "versionString" parameter of the OMID Partner object. |
source.ext.schain |
|
Object |
Supply Chain Object. |
Required Parameters to be aligned with COPPA, CCPA, GDPR, CalOppa Regulations |
|||
regs.ext |
gdpr |
String |
Whether or not the request is subject to GDPR regulations, where 0 = no, 1 = yes. |
regs |
coppa |
Integer |
Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. |
regs.ext |
us_privacy |
String |
UC privacy string. |
user.ext |
consent |
String |
GDPR consent string |
device |
dnt |
Integer |
Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track |
device |
lmt |
Integer |
“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. |
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”
Comments
0 comments
Please sign in to leave a comment.