Server side ad requests (via JSON API)

Use the JSON Ad Server endpoint to request ad items in JSON format from the ad server.

The Ad Response will include details of your advertisement and relevant tracking information. The ad item can then be styled before being displayed to the user for a truly native ad - one that matches the look and feel of its display environment. JSON ads can be displayed on websites, mobile apps, chatbots, billboards, smart mirrors, elevators, and many other platforms.

A condensed version of this article is also available in our API documentation.

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, which used to be called "banners"
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.
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 callback URL. Must be called by your application before AdButler will record an impression
is_redirectable Optional property (see Advanced Usage below)
eligible_url A callback URL typcally requested when an ad is rendered on a page. (Requires the Viewability feature, see Advanced Usage below)
viewable_url A callback URL which should be requested after your viewability requirements have been met. (Requires the Viewability feature, see Advanced Usage below)

Setting up JSON Ad API

  1. Go to the section of the relevant zone (Your AdButler > Publishers > Your Publisher > Your Zone).
  2. Click on Get Zone Tags/JSON Ad API on the right menu. The Zone Tags window will appear.
  3. Under Type, choose JSON Ad API.
  4. Fill in the Click Macro and Extra Data fields as necessary.
  5. Copy the generated zone tag at the bottom field and paste it on your page or template.

A sample JSON Ad API zone tag

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, you will find the properties image_url and redirect_url. These are the required properties for a bare-bones clickable image ad.

Raw HTML and Rich Media Ads

If the ad returned in the JSON response is a Custom HTML or Rich Media ad, all the markup required for it will be returned in the body field of the response. You'll use this to render the ad rather than the image_url and redirect_url fields.

Client-Side Impression Tracking

If you have Accupixel enabled in your AdButler settings you'll see the accupixel_url field returned in your JSON response. When this URL is present in the response it must be rendered to the page as a pixel for us to track an impression.

If Accupixel is not enabled on your account, we'll track the impression at the same time as we send the JSON response. The accupixel_url field will not be present in the response, and you won't need to draw anything to the page to count the impression.

CLICK_MACRO_PLACEHOLDER

When you generate your JSON Ad API links you'll notice the ;click= parameter at the end. If you (or your publisher) have your own click tracking link that you'd like to use to track the click, you will pass it into this parameter. This parameter must always be the last parameter in the request. If you don't need to pass us a click tracking link, we recommend removing the ;click= parameter altogether. This will make it easier to add or remove other parameters that you might need without affecting the click-through of your ads.

Requesting via POST

The JSON Ad API can also be accessed via the HTTP POST method. Done this way, you'll pass in your parameters as a JSON object. All of the parameters are the same as those indicated below. Here's a quick example of what one POST body might look like:

POST https://servedbyadbutler.com/adserve
{
    "ID" : 171230,
    "size" : "300x250",
    "setID" : 373469,
    "type" : "json",
    "pid" : "123456",
    "place" : 0
}

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=..."
    }
  }
}

Keyword Targeting

Passing keywords into the ad request allows for advanced targeting options within the AdButler platform.

To pass in first party data and keywords into the ad request, you simply need to add the kw= query parameter into the request.

Let's say we want to pass along the keywords "apples" and "pears", you'd simply add kw=apples,pears

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

URL Targeting

To make use of our URL Targeting feature, we need access to the URL of the page where the ad is shown. With our client-side ad tags, we just read the HTTP Referrer header. However, if you're making a server-side request, you'll need to pass us the referrer through the ;referrer= parameter. Make sure that the page URL is URL Encoded.

Example: https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;referrer=https%3A%2F%2Fadbutler.com%2Fhelp%2Farticle%2Fjson-ad-tag-api

Geographic Targeting

If you're doing server side ad requests, and you want to geographically target your campaigns, you can simply add the ip= query parameter into the request and provide the IPv4 address used for targeting.

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

Platform Targeting

If you're doing server-side ad requests and you want to use platform targeting on your campaigns, you'll need to pass us the device data through the following parameters:

Parameter Description Example
ua The user's User Agent string (URL encoded). Roku4640X%2FDVP-7.70%20(297.70E04154A)
sw The user's device's screen width. 1920
sh The user's device's screen height. 1080
spr The user's devices' screen pixel ratio. 3

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 handle the refreshing. You'll use the refresh_time field to know how long to wait before making your next request. The refresh_url field will be the full request you need to make for the next ad. Continue this loop until your response no longer contains a refresh_time and refresh_url.

Unique Delivery

If your zone has Unique Delivery enabled you'll need to add a couple of extra parameters to your JSON Ad API requests to take advantage of it. The first is the pid or "Page ID". This is a random number that should be the same for every ad request from the same page. The second is place. This represents the count of the number of times a zone has been requested on the same page. Using both of these parameters is how our system knows to not send back the same ad more than once. Here's an example of calling the same zone twice on the same page:

https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;pid=123456;place=0
https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;pid=123456;place=1

Roadblocks

If you wish to roadblock a JSON request so that all the requests rfrom a single page come from assigned campaigns to your zones that share the same roadblock tag, you will want to ensure that the pid parameter (page id) remains the same for all calls on a single page. The first JSON call from a new page (pid) will set the roadblock for the rest of the calls from that page id. Any additional calls from that same page id (pid) will inform AdButler that it must serve a campaign assigned to that zone with a matching roadblock tag otherwise, if there is no matching roadblock, "No Ad" will be returned.

User Frequency Capping

Traditionally our User Frequency Capping is handled through cookies on the client-side. However, this isn't an option if you're making your requests on the server-side. Instead you'll have to store and pass us the User Frequency information to and from every request. NOTE This is only available when using the POST request method on your JSON Ad API requests. In every JSON response from us you'll receive four important fields: 'placement_id', 'user_frequency_views', 'user_frequency_start', and 'user_frequency_expiry'. If you receive these 'user_frequency' fields and they are non-empty you'll have to store the values and pass them back to us in your next request to the same zone. You can pass them to us in your request's POST body using the user_freqfield like so:

POST https://servedbyadbutler.com/adserve
{
    "ID" : 171230,
    "size" : "300x250",
    "setID" : 373469,
    "type" : "json",
    "pid" : "123456",
    "place" : 0,
    "user_freq" : [
        {
            "placement_id" : 1016336,
            "start" : 1604465307,
            "expiry" : 1606193307,
            "views" : 2
        }
    ]
}

That's all there is to it! You don't need to perform any of the capping logic on your own. Just record what you get in your responses, and send it back on every request. One thing to keep in mind is that you may have more than one placement in your zone that has frequency capping. In that case, you will send us back 2 JSON objects in the user_freq array (one for each placement).

Viewability

This section covers viewability in the JSON Ad API, and requires that you have the Viewability feature enabled.

AdButler follows the IAB standard for Viewability. We consider an ad "viewable" when at least 50% of its pixels have been in the user's viewport for at least 1 second. We recommend that you trigger your viewability callbacks with the same criteria for consistency across your account. However, the JSON Ad API lets you fine tune your approach to meet advertiser requirements.

With the Viewability features enabled, you'll see two additional callback URLs in your responses.

{
    "status": "SUCCESS",
    "placements": {
        "placement_1": {
            ...
            "viewable_url": "https://...",
            "eligible_url": "https://...",
            ...
        }
    }
}

eligible_url - Request this callback URL immediately after your ad has been rendered into the page.

viewable_url - Request this callback URL as soon as your desired viewability criteria are met (we recommended at least 50% of ad viewable for over 1 second).

If you have Accupixel enabled, you must trigger eligible_url after Accupixel. Then, when your page's JS indicates that the ad has been viewed, you can trigger viewable_url.

Data Keys

To make use of our Data Keys feature, you have two options. For a GET request you can pass in the values using the _abdk[] parameter like so: https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;_abdk[bird]=duck;_abdk[bug]=ant

If you're using a POST request, you can use the _abdk_json field to pass them all as an object. Like so:

POST https://servedbyadbutler.com/adserve
{
    "ID" : 171230,
    "size" : "300x250",
    "setID" : 373469,
    "type" : "json",
    "_abdk_json" : {
        "bird" : "duck",
        "bug" : "ant"
    }
}

Can't find what you're looking for?

Send us an email

hello@adbutler.com
Visit the blog

Visit the blog

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