Ad Request and Response Examples
Last updated on August 10, 2020
Below are examples of each type of ad request in different formats and a sample response.
Ad Request Examples
The following are examples of different types of ad requests for JSON and JSONP responses.
Ad request type | Format | Example |
---|---|---|
Standalone | JSON | http://delivery_server_domain/w/1.0/arj?auid=6 |
JSONP | http://delivery_server_domain/w/1.0/arj?auid=6&callback=foo | |
Ad unit group | JSON | http://delivery_server_domain/w/1.0/arj?pgid=123 |
JSONP | http://delivery_server_domain/w/1.0/arj?pgid=123&callback=foo | |
Multi-ad unit | JSON | http://delivery_server_domain/w/1.0/arj?auid=1,2,3 |
JSONP | http://delivery_server_domain/w/1.0/arj?auid=1,2,3&callback=foo |
You can also combine auid
and pgid
IDs in a single ad request. The following request for multiple ad units and an ad unit group will fulfill multiple ad units in a single request:
http://delivery_server_domain/w/1.0/arj?auid=1,2,3&pgid=123
Parameter | Description |
---|---|
http | The protocol. If your ad space uses SSL/TLS, use https instead. |
delivery_server_domain | The hostname of your OpenX delivery server. |
/w | Indicates the web delivery medium. |
/1.0 | Indicates version 1.0 of the OpenX Supply API. |
/arj | Indicates a request to serve a JSON delivery response (/arj) . |
? | Separates the ad request from the ad request parameters. |
auid | The ad unit ID. |
pgid | The ID of the ad unit group. |
& | Separates each parameter. |
callback | Indicates the JavaScript function wrapper to return in the JSONP response. |
Structured Responses
When OpenX receives an ad request for a structured response, it returns one of the supported response formats, which your custom application can interpret and render appropriately. It is a good idea to test a few ad requests to see what the response looks like. This way, you can review how OpenX represents its objects in its response, and make sure that your custom application configuration is able to handle the response.
In the case of a request for a JSONP response, when OpenX receives the ad request, it returns the JSON structure, wrapped in the JavaScript function, which was set in the ad request’s callback
parameter. The response from OpenX is a call to the specified JavaScript function, using the JSON structure as its input.
All structured responses contain the following elements for managing refresh:
refresh_delay
: represents the number of seconds to wait between ad reloadsrefresh_max
: represents the maximum number of times to reload a new ad
To use these fields, your client application must:
Identify the refresh_delay and refresh_max fields in the JSON response.
Append
rc=COUNT
whereCOUNT
is replaced with the iteration of the reload (for example, first refresh hasrc=1
and third hasrc=3
).For example:
max = response.refresh_max delay = response.refresh_delay for (i=1;i++;i<=refresh_max) { sleep(delay) url = build_url() + "&rc=" + i fetch_ad(url) }