Ad request and response examples

Last updated January 16, 2019

Below are examples of each type of ad requestCommunication from a web browser or app to an ad server to display an ad. in different formats and a sample response.

If needed, see also Mobile ad request examples.

Ad request examples

The following are examples of different types of ad requests for XML, JSON, and JSONP responses. See also Mobile ad request examples.

Ad request type

Format Example

 

 

Standalone

XML
http://delivery_server_domain/w/1.0/arx?auid=6
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 groupA collection of ad units where related ads display together at the same time.

XML
http://delivery_server_domain/w/1.0/arx?pgid=123
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 unitThe smallest inventory component that represents the space on a site where ads display.

XML
http://delivery_server_domain/w/1.0/arx?auid=1,2,3
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/arx?auid=1,2,3&pgid=123

Where:

  • http is 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

  • /arx or /arj. Indicates a request to serve structured XML delivery response (/arx) or 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 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 XML or JSON response.

  2. Append rc=COUNT where COUNT is replaced with the iteration of the reload (e.g., 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)
    }

If needed, see also Mobile ad response examples.

Fill out my online form.