A picture of a generic desk

JSON Work: Banners On Command

Read Time: 6 minutes

What do you do when you need another ad? Sure, AdButler’s async tags work really well on most pages. And the JSON zone tag fills in the gaps where you can’t use normal tags, like in an app, or when you need to interact directly with the page, such as an interstitial. But what about websites where the page doesn’t change, whether they’re infinite scroll, web apps, or anything else? There’s a unique problem when working in these kinds of spaces. JSON’s still the solution. But we have to do something a bit different. First, the problem:

Placing a normal zone tag works for the first page load, but as the user continues to spend time on your website, you want to keep showing them ads without refreshing. You don’t want to just rotate them on a counter or anything like that, though. Your page might emulate page loads, so why not rotate ads when that happens? You’d need a function, an action, that loads a new ad whenever you want. And that’s what we have here:

Today’s JSON work focuses on the banner creation function I used above. Basically, it takes in a few parameters and spits out an ad where ever you want it. You can find the template for it on our Ad Format page, and the breakdown below.

An AdButler JSON response

What are we making?

We’re building a function that can display an ad from an AdButler zone in a specific spot. The function needs to be able to handle unique delivery, and it needs to be able to display the main types of banners (Image, HTML5 Rich Media, Custom HTML) with no problems. I’m going to be using bits of the Interstitial and Carousel JSON integrations today, so if you’ve read those articles, some of this stuff should be familiar.

As always, I’m making use of jQuery today to smooth over some things. The template is also just the function, sans HTML, as it’s not particular to any one layout.

Very simple HTML today. We just have a link to jQuery, a button that runs the function, and a <div> that serves as our target. It has the super generic identifier of ‘advertisement’, but in the real world you’ll want to give it something actually specific (like ‘ad-spot-1’).

The Code

The beginning part of our script defines a few variables: the JSON zone tag, the pageID, and the iterator. The JSON zone tag is what we’re getting the ad from, while the other two variables are only needed for unique delivery.

Unique delivery allows us to make sure ads only repeat once all ads in a zone have been served. For unique delivery to work, AdButler needs an identifier for the page and to know how many ads have been requests for that page already. The formula here generates a random six digit number to use as the page id, while the iterator will increase every time a new ad is loaded.

Even if you’re loading multiple ad zones on a page, you will only need one page id. However, for each unique zone on the page, you will need another iterator. If that’s the case, you might want to create a 2D array (or just use a bunch of variables).

Our next bit of script is the wrapper function that handles the retrieval of the banner. You’ll notice we have four parameters: ‘zone’, ’id’, ’iterator’, and ’pageID’. You’ll want to pass in the parameters we created in the previous bit to the function when it is called. The only one we haven’t covered is ‘id’, which is the id of the <div> where you want the banner displayed (which in our case, you guessed it, is ‘advertisement’).

The first thing this function does is insert the pageID and iterator into the zone tag so AdButler gets that information. It splits apart the zone tag and glues it back together with the new values, and then places an ajax call (basically sends a request for the banner) to the zone tag. The function then passes the returned data into the buildBanner function (taken from the interstitial example), along with the id, to display the ad.

An important piece here is what happens if the tag does not return a banner. Once again, we’re looking at unique delivery. AdButler will return “NO_ADS” for a variety of reasons, whether the zone is empty, targeting doesn’t match, or, and this is the important one, if unique delivery is turned on and all banners have been served once. The if statement checks to see if an ad has already been served (by looking at the iterator), and if at least one ad has been served, it’ll restart the process back with an iterator of 0.

Our final piece of code builds the banner. First, it clears out any existing banner, and then sets the target div to be the dimensions of the zone. Depending upon whether the banner is an Image or a Custom HTML/Rich Media Banner, it builds the banner a different way. Finally, the function adds in any tracking pixels included, and you’re off to the races.

Once again, all you need to do is call the function with the four parameters. If you’re not using unique delivery, you can either pass in 0’s or nothing at all for the last two parameters. Ignoring unique delivery will make ads sometimes repeat, but if you’re okay with that, I am too. Since we made a function, you can tie the function to a button press or a click or really any event you want. All you need to do is include the script on your page somewhere.

What next?

Feel free to mess with the code, and let me know if you come up with any problems or unique situations. As well, if you’re interested in some other integrations, check out our Ad Format page here.

Liam Workman


Liam is an account manager and blog king at SparkLit, the SaaS company behind AdButler and FourEyes. He loves rock climbing, hiking, coding, and being your friend.