Advertising with the IMA SDK, p. 3

Over the last posts (0–2), we have learned a ton about how to set up the IMA SDK, and how to request single ads and playlist ads. Now, everything is as great as can be and you are monetizing a lot! However, you ponder, almost philosophically — what if something goes wrong and how you would go about troubleshooting it. Fair enough. We shall cover this topic in this blog post.

Today, I will explore the different approaches to troubleshooting should issues arise from your implementations. We will walk through some tools that are quite helpful for such cases.

Woohoo! What tools do I need?

Charles Proxy: Super helpful when you need to proxy your network traffic and peek in it to see what’s happening between your device and the ad server. Charles acts as a man-in-the-middle tool and reveals everything that comes in and goes out. Any other proxying tools will do, as well.

Browser Console: Every web browser has a built-in console. Use this to see if any visible log is written to it by IMA. For example, if the ad tag is returning empty VAST, you can log the ad error object and write it to the console for visibility. If you run IMA natively for mobile (Android and iOS), utilize your IDE’s logcat.

Network Link Conditioner: You want to know how your implementation performs under slow network conditions. This is a useful tool to simulate such environments. Just don’t forget to disable it after testing!

Others: a localhost where you can test things out offline, a remote server (FTP, Amazon Cloud, et al.) to see things live, an XML validator to check the sanity of your VAST, and probably some knowledge of basic TCP/IP!

Fabulous! Now how do I actually troubleshoot a problem?

Glad you asked. Let’s troubleshoot a fairly common issue we tend to see a lot (or not seeing — pun intended): no ad is playing in your implementation.

First, when we don’t see an ad playing, there can be many common origins where the culprit lies. Maybe the ad request wasn’t made? Or probably your app makes the request but it is getting back an invalid VAST response that IMA can’t understand and render? Well, no matter what it is, Charles Proxy is a great tool here to start with. Start up Charles, and record. Launch your app (if your implementation is browser-based, you can utilize your browser’s console to the same effect) and initiate your ad request.

Fig. 1: Charles Proxy showing a successful ad request against DFP’s ad server.

As you can see from the screenshot, there is an entry on the left-side panel that falls under “”. It is your ad request. If you see that, you can reason with 99.99% certainty that your app has sent out an ad request to the ad server. If there is no such entry, eh — maybe there is a firewall in place, or probably you forgot to include the line that sends the ad request? On the right-side panel, there is other useful information if you are concerned about network performance and latency.

Now, to verify whether the server has received the request and replied with a meaningful VAST response, flip to the “Response” tab in Charles:

Great — something came back and it looked structurally meaningful! If the response comes back empty, you might want to check your ad trafficking and/or the structure of your ad tag. Sometimes there might be frequency capping in place that restricts ad serving based on various factors (devices, geo, cookies, et al.), so be sure to look out for those as well. But here let’s work from the premise that we successfully receive a response.

Given that, the next point to check is probably your IDE’s (if app-based) or browser’s console. For any ad errors, there are corresponding ad error events that are thrown. For example, say if you see an empty response in Charles, if you look at the log output, you will probably see an error code 1009, which is the constant for google.ima.AdError.ErrorCode.VAST_EMPTY_RESPONSE. Pretty neat, ain’t it?

So if your code isn’t logging any error information, now is the time to rectify that. There are various things you can extract from the error object, such as its name, constant, et al. Here is how:

function onAdError(adErrorEvent) {
// Handle the error logging.
var error = adErrorEvent.getError();
 console.log(“Error — “ + error.toString());
console.log(“getErrorCode() — “ + error.getErrorCode());
console.log(“getInnerError() — “ + error.getInnerError());
console.log(“getMessage() — “ + error.getMessage());
console.log(“getType() — “ + error.getType());
console.log(“getVastErrorCode() — “ + error.getVastErrorCode());
 adsManager.destroy(); /* don't forget to destroy the adsManager in case of a fatal error */

And that logic will produce the following output (I’m using 403 since I have it handy, even though we were talking about 1009):

Error — AdError 403: Linear assets were found in the VAST ad response, but none of them matched the video player’s capabilities.
getErrorCode() — 403
getInnerError() — undefined
getMessage() — Linear assets were found in the VAST ad response, but none of them matched the video player’s capabilities.
getType() — adPlayError
getVastErrorCode() — 403

Hopefully by this point you will get down to the culprit of the issue with the help of the detailed error information. 403 is a great example of when an ad isn’t playing — IMA finds media assets in the VAST but none of them can be rendered on the requesting platform. Think playing WebM on IE, which isn’t supported.

If you do run into a 403 like above, make sure you set up trafficking differently. For example, if you know a part of your audience is on IE, make sure you include some media types that IE can render (for example, MP4).

That is an awesome demonstration! Thanks a bunch!

Thank you for checking it out. See you next time!

- Vu, IMA SDK Team

A single golf clap? Or a long standing ovation?

By clapping more or less, you can signal to us which stories really stand out.