OpenRTB Ad Request Parameters

Publishers

Last updated on November 30, 2020

To better characterize your inventory, you can send additional data about your ad units to buyers in the OpenX Ad Exchange using OpenRTB values. You do not need to pass all OpenRTB values because OpenX automatically identifies and passes certain OpenRTB fields for you.

on this page

• Sample JSON Object Including OpenRTB Values
• Recommended OpenRTB Fields
• OpenRTB Fields Set by OpenX
• OpenRTB Fields Passed by Publishers

The openrtb ad request parameter supports a percent-encoded string generated from JSON objects with supported OpenRTB values.

Sample openrtb parameter included in an ad request

The following ad request shows how you can include various ad request parameters, including the openrtb parameter, which specifies a percent-encoded string.

http://delivery_server_domain/w/1.0/acj?
o=7889550390&callback=OX_7889550390&auid=537627288&res=320x568x32&plg=qt%2Cpm&ch=UTF-8&tz=420&ws=320x50&sd=1&openrtb=%7B%22cur%22%3A%20%5B%22USD%22%5D%2C%20%22site%22%3A
%20%7B%22publisher%22%3A%20%7B%
22domain%22%3A%20%22foobar.com%22%2C%20%22cat%22%3A%20%5B%22IAB3-1%22%5D%2C%20%22id%22%3A
%20%228953%22%2C%20%22name%22%
3A%20%22foobar.com%22%7D%2C%20%22domain%22%3A%20%22www.example.com%22%2C%20%22page%22%3A%20%22http
%3A//www.example.com/
1234.html%20%22%2C%20%22id%22%3A%20%22102855%22%2C%20%22cat%22%3A%20%5B%22IAB3-1%22%5D%7D%2C
%20%22imp%22%3A%20%5B%7B%
22banner%22%3A%20%7B%22h%22%3A%20250%2C%20%22pos%22%3A%200%2C%20%22w%22%3A%20300%7D%2C%20%22id
%22%3A%20%221%22%2C%20%
22bidfloor%22%3A%200.03%7D%5D%2C%20%22at%22%3A%201%2C%20%22device%22%3A%20%7B%22ip%22%3A
%20%22123.145.167.10%22%2C%20%
22ua%22%3A%20%22Mozilla/5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X
%2010_6_8%29%20AppleWebKit/537.13%20%28KHTML%2C%
20like%20Gecko%29%20Version/5.1.7%20Safari/534.57.2%22%7D%2C%20%22id%22%3A
%20%2280ce30c53c16e6ede735f123ef6e32361bfc7b22
%22%2C%20%22user%22%3A%20%7B%22id%22%3A%20%2255816b39711f9b5acf3b90e313ed29e51665623f%22%7D%7D

Sample JSON object including OpenRTB values

The following JSON object shows the structure of the OpenRTB data before removing unnecessary white space and before percent encoding.

{'cur': ['USD'],
 'device': {'ip': '123.145.167.10',
             'ua': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2'},
 'id': '80ce30c53c16e6ede735f123ef6e32361bfc7b22',
 'imp': [{'banner': {'h': 250, 'pos': 0, 'w': 300},
           'bidfloor': 0.03,
           'id': '1'}],
 'site': {'cat': ['IAB3-1'],
          'domain': 'www.example.com',
          'id': '102855',
          'page': 'http://www.example.com/1234.html ',
          'publisher': {'cat': ['IAB3-1'],
                        'domain': 'example.com',
                        'id': '8953',
                        'name': 'example.com'}}}
}

To improve performance, remove all unneeded white space and line breaks from your JSON object before generating a percent-encoded version of it as shown in the following example.

JSON string prepared for percent-encoding

{"cur": ["USD"], "site": {"publisher": {"domain": "example.com", "cat": ["IAB3-1"], "id": "8953", "name": "example.com"}, "domain":
"www.example.com", "page": "http://www.example.com/1234.html ", "id": "102855", "cat": ["IAB3-1"]}, "imp": [{"banner": {"h": 250,
"pos": 0, "w": 300}, "id": "1", "bidfloor": 0.03}], "device": {"ip": "123.145.167.10", "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X
10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2"}, "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22"}

You can pass as many supported OpenRTB fields as you find useful to characterize your inventory except for those that cannot be passed by publishers.

Recommended OpenRTB fields

The following OpenRTB fields are recommended because they provide the most value to buyers.

• For a complete list of fields that you can pass, see OpenRTB fields passed by publishers.
• To understand which fields-are auto-detected or, for other reasons, cannot be passed by publishers, see OpenRTB fields not passed from publishers.

OpenRTB Fields Set by OpenX

Last updated on November 6, 2020

OpenX passes certain OpenRTB fields to OpenX Ad Exchange buyers. You cannot set or override these fields. For example:

• Values that are automatically detected, such as location data for a mobile device.
• Values that are set by OpenX to characterize or structure the bid request.

OpenRTB Fields Passed by Publishers

Last updated on January 16, 2019

You can pass as many supported OpenRTB values as you find useful to characterize your inventory except for those that cannot be passed by publishers. However, passing too many fields can negatively impact the performance of the ad request, so only add fields that will help buyers to target your inventory.

BidRequest fields

Site fields

BidRequest.site

App fields

BidRequest.app

Publisher fields

BidRequest.app.publisher or BidRequest.site.publisher

Content fields

BidRequest.app.content or BidRequest.site.content

Device fields

BidRequest.device

Geo fields

BidRequest.device.geo or BidRequest.user.geo

BidRequest.user

Each BidRequest object can contain a User object, which provides details about the end-user.

User extensions object fields

BidRequest.user.ext

Data fields

Segment fields

BidRequest.user.data.segment

Regs object fields

BidRequest.regs

Regs extensions object fields

BidRequest.regs.ext