Ad Request Parameters
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:
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
vmaxdvideo 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.
Unless described as required, all parameters are optional (if applicable to the type of ad request) or ignored (when not applicable).
|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:
• For multiple ad units:
|Ad 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.|
|Custom 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.|
|Cache 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 |
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.
|Character encoding. Indicates the character set for the current page.|
|Client 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: |
|The subject matter category for the presented video content. Use IAB category labels.|
Separate multiple categories with commas. For example,
|The time duration, in seconds, of the presented video content. The value is a positive integer.|
|The title of the presented video content. The value is a string.|
|Indicates whether the request is subject to the General Data Protection Regulation (GDPR).|
|Indicates 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.
See the IAB’s GDPR Consent String Specification for more information.
|Client IP address.|
|Indicates the GPS latitude location, in decimal form, of the end-user. You should send the |
|Indicates the GPS longitude location, in decimal form, of the end-user. You should send the |
|Indicates the source of the end-user’s location data, which can be one of the following:|
You should send the
|Indicates the source of the user’s geographic location details.|
|Maximum bitrate. For a video ad unit, indicates the maximum bitrate (in Kbps) of video ads that can serve.|
|Minimum bitrate. For a video ad unit, indicates the minimum bitrate (in Kbps) of video ads that can serve.|
|Specifies a string with supply-side OpenRTB data to be passed to OpenX Ad Exchange buyers.|
Note:Do not specify this parameter for iFrame or image ad requests. It will cause an error.
|Plugins. Indicates any plugins enabled in the user’s browser, such as:|
|Redirect. Indicates the click redirect URL:|
Note: Any of these redirect parameters must be the last parameter in an ad request URL or click URL string.
|Refresh count. Indicates the current number of refreshes for ads served through the ad tag, as counted by OpenX.|
For custom implementations, your client application adds it and sets it with each refresh.
|Refresh 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).
|Referrer. Indicates the URL that directed the user to the current page. Setting this parameter overrides any referrer information passed in the HTTP headers.|
|Resolution. Indicates the screen resolution of the user’s browser (screen width x height x color depth).|
|Refresh 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
|Enables Child’s Online Privacy Protection Act (COPPA) regulations.|
Refer to the IAB’s OpenRTB 2.5 specification for more detailed information on COPPA compliance and regulations. For example:
|Click target. Indicates the browser window target when a user clicks an ad on the page, which can be one of the following:|
|Topic ID. Indicates the content topic for the page.|
|Timezone. Indicates the time zone of the user’s web browser.|
|Full HTTP path of the user’s current page.|
|Passes the |
Click here for information about the
Click here for details of the
|Video bandwidth. Indicates the maximum bandwidth for the video ad, in bits per second.|
Use this parameter as an override for the ad unit setting.
|Video height. Indicates the expected height dimension of the video ad, in pixels.|
Use this as an override for the ad unit setting. For example:
|Video maximum duration. Indicates the maximum length of the video ad, in seconds.|
Use this as an override for the ad unit setting.
|Video out-stream. Indicates video out-stream inventory when the following values are passed:|
|Video - Rewarded. Indicates the inventory is opt-in video, based on the following:|
|Video streaming protocol. Indicates the streaming protocol to use for the video ad.|
Use this as an override for the ad unit setting.
|Video width. Indicates the expected width dimension for the video ad, in pixels. Use this as an override for the ad unit setting.|
|User ID. Indicates the customer-provided user ID, if different from the Device ID.|
border attribute. This guide does not go into detail about how to use common HTML attributes. For more information, refer to www.w3schools.com.
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.