Link Search Menu Expand Document

PDF

Ad Request Parameters

Publishers

Last updated on August 17, 2020


OpenX uses parameter values (also known as “query args”) during ad selection to target the most appropriate ads to your ad space. The table below describes the parameters that OpenX supports in its ad requests. Depending on your integration, in addition to the ad request parameters listed below you may also need to use mobile or OpenRTB parameters.

You can also set parameters for your ad requests by including key-value pairs: key=value For example, auid=1234 specifies the ad unit ID, which is required in all standalone ad requests. For details, see Custom variables. Depending on the type of ad request, OpenX may do one of the following:

  • Ignore parameters that are not applicable to the type of ad request. For example, the vmaxd video ad request parameter is ignored if included in an image ad request.
  • Return an error if one or more parameters are not valid for the ad request.
NOTE

Unless described as required, all parameters are optional (if applicable to the type of ad request) or ignored (when not applicable).

ParameterDescription
auid
(Required)
Ad unit ID which indicates the unique ID for the ad unit where you want to serve an ad. For example:
• For a single ad unit: auid=1234
• For multiple ad units: auid=1234,4321,9876
ausAd unit sizes. Indicates a comma-delimited list of available ad sizes. To use this parameter, you must include additional ad unit sizes when you create your ad unit. For details, see flexible ad units.
For example: aus=728x90,970x90
c.key=valueCustom variable, communicates additional information about the ad space, such as details of app content, ad space location, or user-specific information. For details, see custom variables in ad requests.
For example: c.gender=1
callbackIndicates the JavaScript function call with which to wrap the JSON structure using JSON with padding (JSONP) standards. Required only for JSONP responses to arj (JSONP) and /avj (video JSONP) requests.
cbCache busting. A dynamically-generated random number assigned to the request to avoid browser caching. If you generate an HTML ad tag in the UI, OpenX includes the cb parameter in the ad tag as follows: cb=INSERT_RANDOM_NUMBER_HERE.

When implementing image and iFrame ad tags for HTML ad requests, replace the INSERT_RANDOM_NUMBER_HERE value with a random number, such as a timestamp or a number automatically generated by your CMS. If a user requests the same page again, the browser will invoke a new ad request rather than serving an ad from the cache.
chCharacter encoding. Indicates the character set for the current page.
csClient state. Indicates a unique ID for the ad unit and user to communicate between the click URL and the ad. This parameter is required for image ad tags and ignored for all other types of ad requests. This parameter only accepts values which use the following characters: a-z, A-Z, 0-9, _ (underscore), or - (hyphen).
content.catThe subject matter category for the presented video content. Use IAB category labels.
Separate multiple categories with commas. For example, content.cat=IAB1-3,IAB2-4
content.lenThe time duration, in seconds, of the presented video content. The value is a positive integer.
content.titleThe title of the presented video content. The value is a string.
gdprIndicates whether the request is subject to the General Data Protection Regulation (GDPR).
0 = false
1 = true (the request is subject to GDPR)
gdpr_consentIndicates that the user has consented to having his or her data collected by the publisher’s site, as mandated by the GDPR.

The string format, as specified by the IAB, is the daisybit.
For example:
BOON9OgOON_SYABABADEAa-AAAARh7______b9_3__7_9uz_Kv_K7Vf7nnG072lPVA9LTOQ6gEaY

See the IAB’s GDPR Consent String Specification for more information.
ipClient IP address.
For example: 69.89.31.226
latIndicates the GPS latitude location, in decimal form, of the end-user. You should send the lt parameter with lat/lon.
For example, lat=37.530676
lonIndicates the GPS longitude location, in decimal form, of the end-user. You should send the lt parameter with lat/lon.
For example, lon=-122.262447
ltIndicates the source of the end-user’s location data, which can be one of the following:
1 (GPS/Location Services)
2 (IP Address)
3 (User Provided. For example, a zip code on a website’s registration form)
You should send the lt parameter with lat/lon. For example, lt=1

Note: For 1 to be available for a mobile app, two criteria must be met. The publisher must enable sending location and source in the app, and the end-user must agree to allow location sharing with prompted by the app.
ltsrc
(Deprecated)
Indicates the source of the user’s geographic location details.

If the ltsrc parameter has any value, the latitude and longitude are considered to have been derived from the device’s GPS location. Otherwise, the latitude and longitude were derived from an IP address.
maxbitrateMaximum bitrate. For a video ad unit, indicates the maximum bitrate (in Kbps) of video ads that can serve.
Default: maxbitrate=4000
minbitrateMinimum bitrate. For a video ad unit, indicates the minimum bitrate (in Kbps) of video ads that can serve.
Default: minbitrate=240
oIndicates a random number assigned to the request that helps scope the response from the server. This ensures that multiple server responses do not collide and is useful if you are writing your own synchronous JavaScript ad tags and do not use the OpenX JavaScript tag library.

For example, when you build your own tag library, send OpenX the required inputs, and parse its output. This parameter is optional for JavaScript ad tags, mobile ad requests, mobile video ad requests, and video ad requests. It is ignored by other types of ad requests.
openrtbSpecifies a string with supply-side OpenRTB data to be passed to OpenX Ad Exchange buyers.
pgidPage ID. Indicates the unique ID for the predefined ad unit group. This parameter is optional for JavaScript ad tags, mobile video ad requests, and video ad requests.

Note:Do not specify this parameter for iFrame or image ad requests. It will cause an error.
plgPlugins. Indicates any plugins enabled in the user’s browser, such as:
pdf (Adobe Acrobat Reader)
qt (QuickTime)
rp (Real Media Player)
shk (Adobe Shockwave)
sl (Silverlight)
swf (Flash)
wmp (Windows Media Player)
r, r0, r1, or r2Redirect. Indicates the click redirect URL:
r is a single-escaped URL. For example: http%3A%2F%2Fwww.clickredirectURL.com%3Fsome%3D1%26others%3D2F
r0 is an unescaped URL. For example: http:/www.clickredirectURL.com?some=1&others=2
r1 is a single-escaped URL (same as r).
r2 is a double-escaped URL. For example: http%253A%252F%252Fwww.clickredirectURL.com%253Fsome%253D1%2526others%253D2

Note: Any of these redirect parameters must be the last parameter in an ad request URL or click URL string.
rcRefresh count. Indicates the current number of refreshes for ads served through the ad tag, as counted by OpenX.

This parameter is not initially set in the ad tag. For image, iFrame, JavaScript, and video ad requests, OpenX adds it and then automatically sets it with each refresh. See also, Structured response.

For custom implementations, your client application adds it and sets it with each refresh.
rdRefresh delay (in seconds) for refreshing an iFrame.

This value must be an integer ≥ 1. If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh delay setting for this ad unit (as set when creating or editing the ad unit or its container site).
refReferrer. Indicates the URL that directed the user to the current page. Setting this parameter overrides any referrer information passed in the HTTP headers.
resResolution. Indicates the screen resolution of the user’s browser (screen width x height x color depth).
rmRefresh max. Indicates the maximum number of refreshes for ads displayed through the ad request. This value must be an integer ≥ 1.

For example, setting this parameter to a value of 5 would result in the display of a total of 6 ads (which includes the initial display of the ad (non-refresh) and the 5 subsequent displays of the ad (refreshes)). If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh max setting for this ad unit, as set when creating or editing the ad unit or its container site.

This optional parameter only applies to iFrame tags, JavaScript tags, and structured ad responses.
tfcdEnables Child’s Online Privacy Protection Act (COPPA) regulations.
1 (enabled)
0 (disabled)

Refer to the IAB’s OpenRTB 2.5 specification for more detailed information on COPPA compliance and regulations. For example: tfcd=1
tgClick target. Indicates the browser window target when a user clicks an ad on the page, which can be one of the following:
_blank (New window)
_parent (Parent window)
_self (Current window)
_top (Top window)

Note:This parameter is only used for image creatives that display in iFrame and JavaScript ad tags.
tidTopic ID. Indicates the content topic for the page.
tzTimezone. Indicates the time zone of the user’s web browser.
urlFull HTTP path of the user’s current page.
For example: http://yoursite.net/home.html
us_privacyPasses the us_privacy string for the IAB CCPA Compliance Framework.

Click here for information about the us_privacy string.

Click here for details of the us_privacy string.
vbwVideo bandwidth. Indicates the maximum bandwidth for the video ad, in bits per second.

Use this parameter as an override for the ad unit setting.
vhtVideo height. Indicates the expected height dimension of the video ad, in pixels.

Use this as an override for the ad unit setting. For example: 320
vmaxdVideo maximum duration. Indicates the maximum length of the video ad, in seconds.

Use this as an override for the ad unit setting.
vosVideo out-stream. Indicates video out-stream inventory when the following values are passed:
101 (In-read, an out-stream ad format that is placed within the text of a site or app)
102 (In-board, an out-stream ad format that is located at the top of a page)
vrwVideo - Rewarded. Indicates the inventory is opt-in video, based on the following:
1 (Yes)
0 (No)

For example: vrw=1
vstrmVideo streaming protocol. Indicates the streaming protocol to use for the video ad.
Use this as an override for the ad unit setting.
vwdVideo width. Indicates the expected width dimension for the video ad, in pixels. Use this as an override for the ad unit setting.
For example: 480
xidUser ID. Indicates the customer-provided user ID, if different from the Device ID.
For example: xid=234hskhjfdkhjs

If you are performing HTML ad requests with image, iFrame, or JavaScript ad tags, you may be able to specify various HTML attributes that are specific to the tag type that you are using. For example, for an image ad tag, this may include the border attribute. This guide does not go into detail about how to use common HTML attributes. For more information, refer to www.w3schools.com.

NOTE

In cases where a web browser is used to make an ad request, the browser may truncate the an ad request if the resulting URL exceeds its character limits. These limits vary by browser. Set required parameters first, then incorporate optional parameters in your tags.