Link Search Menu Expand Document

PDF

Ad Request and Response Examples

Publishers

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 typeFormatExample
StandaloneJSONhttp://delivery_server_domain/w/1.0/arj?auid=6
 JSONPhttp://delivery_server_domain/w/1.0/arj?auid=6&callback=foo
Ad unit groupJSONhttp://delivery_server_domain/w/1.0/arj?pgid=123
 JSONPhttp://delivery_server_domain/w/1.0/arj?pgid=123&callback=foo
Multi-ad unitJSONhttp://delivery_server_domain/w/1.0/arj?auid=1,2,3
 JSONPhttp://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
ParameterDescription
httpThe protocol. If your ad space uses SSL/TLS, use https instead.
delivery_server_domainThe hostname of your OpenX delivery server.
/wIndicates the web delivery medium.
/1.0Indicates version 1.0 of the OpenX Supply API.
/arjIndicates a request to serve a JSON delivery response (/arj).
?Separates the ad request from the ad request parameters.
auidThe ad unit ID.
pgidThe ID of the ad unit group.
&Separates each parameter.
callbackIndicates 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 reloads
  • refresh_max: represents the maximum number of times to reload a new ad

To use these fields, your client application must:

  1. Identify the refresh_delay and refresh_max fields in the JSON response.

  2. Append rc=COUNT where COUNT is replaced with the iteration of the reload (for example, first refresh has rc=1 and third has rc=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)
     }