Using the JSON ad tag API

Typically a Zone Tag is a short snippet of javascript code or HTML that is placed on a Publisher's website that is used to serve ads to that particular placement.

An alternative method is to use our JSON zone tag (JSON ad API). The JSON zone tag performs the same functionality as other zone tags, in that it determines which ad should be shown given your rules and preferences. The main difference between the JSON zone tag and the others is that the JSON zone tag lets you decide how to render the advertisement, whereas, with the other zone tags, they determine how the ad should be rendered.

By using the JSON zone tag you will have more control over the look and feel of the advertisement.

If you use native advertising on your properties, the JSON ad API provides information on the various portions of the advertisement, and you can put it together to best fit in with the look and feel of your website.

JSON Ad API Properties

Property Description
status Indication of successful operation
placements Container object for placement_1
placement_1 Container for the valid ad item for the zone
banner_id The resource identifier (ID) for the Ad Item (banner)
width Width of the image, as set in the ad item details
height Height of the image, as set in the ad item details
alt_text The alt text tied to the image. Used to describe the ad item for people employing a screen reader.
accompanied_html HTML that is typically included directly below the ad item. Cannot be used to deliver scripts.
target How the ad item will direct the user if it's clicked.
tracking_pixel The URL of an impression tracking pixel.
body Contains the raw HTML needed for Rich Media and Custom HTML ad items.
redirect_url The URL for the clickable link leading to the destination URL
refresh_url For auto refresh zones, this is the URL to use when reloading the zone
refresh_time Number of seconds delay before the zone should auto refresh
image_url The URL for the ad item image
accupixel_url The Accupixel is an impression pixel that double-checks an impression to make sure it's genuine by loading after the ad item.
is_redirectable Optional property (see Advanced Usage below)

To begin using the JSON Ad API

Choose JSON Ad API from the zone tag options

JSON Ad API

If we inspect the value returned by the URL, we can see the structure of the JSON:

{
  "status": "SUCCESS",
  "placements": {
    "placement_1": {
      "banner_id": "519738954",
      "width": "300",
      "height": "250",
      "alt_text": "",
      "accompanied_html": "",
      "target": "_blank",
      "tracking_pixel": "",
      "body": "",
      "redirect_url": "https://ads.domain.com/redirect.spark?MID=...",
      "refresh_url": "",
      "refresh_time": "",
      "image_url": "https://ads.domain.com/getad.img/;libID=711268",
      "accupixel_url": "https://ads.domain.com/adserve/;ID=..."
    }
  }
} 

Inside the JSON document in the placement_1 object, there are the properties image_url and redirect_url. The basics needed for a bare bones clickable image ad.

If your Ad Item doesn't have a destination URL in the Ad Item Details, it will still have a redirect_url in the JSON document. In order to determine if there's a valid destination you can append the parameter ;rf=1 onto the JSON request URL.

Advanced Usage

Determining if an Ad Item has a destination URL

In order to determine if the Ad Item has a destination URL that you need to redirect to, you can insert the parameter ;rf=1 before the click parameter, near the end of your JSON request URL.

https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;click=CLICK_MACRO_PLACEHOLDER

Changes to:

https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;rf=1;click=CLICK_MACRO_PLACEHOLDER

With this additional parameter, the JSON document will have an additional boolean property, is_redirectable.

{
  "status": "SUCCESS",
  "placements": {
    "placement_1": {
      "banner_id": "519738954",
      "width": "300",
      "height": "250",
      "alt_text": "",
      "accompanied_html": "",
      "target": "_blank",
      "tracking_pixel": "",
      "body": "",
      "redirect_url": "https://ads.domain.com/redirect.spark?MID=...",
      "refresh_url": "",
      "refresh_time": "",
      "is_redirectable": false,
      "image_url": "https://ads.domain.com/getad.img/;libID=711268",
      "accupixel_url": "https://ads.domain.com/adserve/;ID=..."
    }
  }
}

Auto Refresh

If your zone is set up to auto refresh, you will make use of the properties refresh_time and refresh_url in your custom code to


Can't find what you're looking for?

Send us an email

hello@adbutler.com

Visit the blog

For more ad serving tips, industry news and AdButler insights.