Escaped vs. unescaped URL macros

Choosing the wrong variant (unescaped/escaped/double-escaped) of a macro that expands to a URL (for example, click macros, view macros, and so forth) almost always prevents the desired creative behavior. In the case of a click-through URL, this means that the creative doesn't click through to the proper destination. For view macros, impressions aren't properly counted by Ad Manager or third-party impression trackers.

Macro placement is complicated by the fact that tracking URLs are frequently chained together to accommodate tracking impressions and clicks in Ad Manager and a third-party server. For instance, an Ad Manager click URL might redirect to a third-party click URL, which might then redirect to the ad landing page. In this case, the order of the URL redirects dictates whether an escaped or unescaped macro should be used.

As a general rule, if the macro comes at the start of the URL chain, the unescaped click macro should be used. If the macro comes at the end of the URL chain, the escaped macro should be used. Escaping the URL is necessary in the latter case because the Ad Manager tracking URL is passed as a parameter to a third-party server, and unescaped reserved characters (defined in RFC3986) in the Ad Manager tracking URL can interfere with the third-party server's parsing of parameters.

For example, an unescaped Ad Manager click URL expands to something like the following (some parameters have been removed or shortened for clarity):

http://adclick.g.doubleclick.net/aclk?sa=l&ai=C8qeK&adurl=

By contrast, the escaped tracking URL would expand to the following:

http://adclick.g.doubleclick.net/aclk%253Fsa%253Dl%2526ai%253DC8qeK%2526adurl%253D

In the escaped URL, URL reserved characters have been escaped (technically, they are double-escaped) using percent-encoding, which renders them safe for inclusion in another URL.

Example macro insertions

Example 1A: Correct Ad Manager click-tracking on custom creative

For this example, let's assume that we have a custom creative that should click through to http://www.google.com/page.html?param1=red&param2=blue

A simple image creative might track clicks like the following:

<a href='%%CLICK_URL_UNESC%%%%DEST_URL_ESC%%' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

In this example, the creative as rendered on the user's browser would be:

<a href='http://adclick.g.doubleclick.net/aclk?sa=l&ai=C8qeK&adurl=http://www.google.com/img.gif%3Fparam1%3Dred%26param2%3Dblue' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

This is a valid and correct click URL, since the Ad Manager click URL is unescaped and the destination URL is properly escaped.

Example 1B: Incorrect Ad Manager click-tracking on custom creative

One common mistake that would break the creative code in the above example would be to use the escaped click URL macro. In the creative code, this would look like the following:

<a href='%%CLICK_URL_ESC%%%%DEST_URL_ESC%%' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

The creative as rendered on the user's browser would be:

<a href='http://adclick.g.doubleclick.net/aclk%253Fsa%253Dl%2526ai%253DC8qeK%2526adurl%253Dhttp://www.google.com/img.gif%3Fparam1%3Dred%26param2%3Dblue' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

This is incorrect—since all the parameters have been escaped, the adclick server can't parse them properly. Instead, the server will interpret this as a request for a page named /aclk%253Fsa%253Dl%2526ai%253DC8qeK%2526adurl%253Dhttp://www.google.com/img.gif%3Fparam1%3Dred%26param2%3Dblue

As this page does not exist, an HTTP 404 (Not found) error is returned by the adclick server, and the user isn't directed to the ad landing page.

Example 1C: Incorrect Ad Manager click-tracking on custom creative

Another common mistake is to use the unescaped destination URL macro. In the creative code, this would look like the following:

<a href='%%CLICK_URL_UNESC%%%%DEST_URL_UNESC%%' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

The creative as rendered on the user's browser would be:

<a href='http://adclick.g.doubleclick.net/aclk?sa=l&ai=C8qeK&adurl=http://www.google.com/page.html?param1=red&param2=blue' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

Note that this particular example might work correctly if the first click server is smart enough to interpret the remaining parameters as URLs and escape them. Ad Manager does rewrite the URL in this case, which allows the click-through to function properly. However, it's unsafe to assume that the server will be able to handle incorrectly formatted click URLs. We strongly recommend using a properly formatted click URL, rather than relying on Ad Manager or a third-party analytics server to handle erroneously formatted URLs.

If the server does not rewrite the incorrectly formatted URL, it will be interpreted as follows:

http://adclick.g.doubleclick.net/aclk?sa=l&ai=C8qeK&adurl=http://www.google.com/page.html?param1=red&param2=blue

In this case, the final '&' character is interpreted as delimiting a new parameter for the FIRST server request, rather than a parameter that's intended to be passed to the server hosting the ad landing page. This may interfere with the click server's processing of the click URL, which may prevent the user from being redirected to the landing page. Even if the user is successfully redirected, it's likely that the second parameter (param2) isn't passed to the landing page.

Example 2A: Correct chaining third-party click tracker to Ad Manager click tracker on custom creative

In some cases, an advertiser might ask you to include a third-party click/view tracker within the creative. When this is requested, the advertiser will typically provide you with a URL that looks something like the following (parameters have been simplified for clarity):

http://ad.doubleclick.net/clk;a;b;c?[insert click-through URL here]

We use a DCM click tracker in this example, but the process is similar for other providers.

When the user clicks on this URL, the browser will first load the ad.doubleclick.net server, causing the click to be recorded. The server will then redirect the browser to the click-through URL specified as a parameter.

Since the goal is to track clicks in Ad Manager as well, you'll want to redirect to Ad Manager before redirecting to the ad landing page. As the Ad Manager click URL is being passed as a parameter to the ad.doubleclick.net server, you must use the escaped click macro.

You should use the double-escaped destination URL macro, since the first click tracker server may unescape the remainder of the URL during processing.

A simple image creative might track clicks like the following:

<a href='http://ad.doubleclick.net/clk;a;b;c?%%CLICK_URL_ESC%%%%DEST_URL_ESC_ESC%%' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

When using a creative template, the third-party click tracker is usually represented within the creative code as a URL placeholder identifier.

The creative as rendered on the user's browser would be:

<a href='http://ad.doubleclick.net/clk;a;b;c?http://adclick.g.doubleclick.net/aclk%253Fsa%253Dl%2526ai%253DC8qeK%2526adurl%253Dhttp://www.google.com/page.html%253Fparam1%253Dred%2526param2%253Dblue' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

Validating macro insertion

In some cases, such as complicated custom JavaScript, the actual format of the URL chain may be difficult to ascertain from the creative code directly. You may have an easier time if you switch to the creative preview tab and open the creative in a new window, then search through the page source or inspect the page DOM elements (e.g., through Dev Tools in Chrome or FireBug in FireFox) to identify how the URLs are being rendered on the page.

The creative preview tab is crucial for validating correct macro insertion. Validating correct click-through behavior within the creative preview tab is easy—when the macros have been inserted properly, clicking the creative will lead to an Ad Manager landing page that confirms the click has been tracked, and then you will be redirected to the landing page for the creative. If either of these steps fails, you have a good indication that the macros have not been placed properly.

Validating impression-tracking macro placement within the creative preview tab is a little more complicated. You must use a network traffic analyzer (e.g., Chrome Dev Tools, Charles, etc.) to ensure that the request for the impression-tracking URL (and any successive redirects to other tracking URLs) completes successfully. If you see any HTTP errors reported during this chain of connections (HTTP 204 is a common error code when macros are placed incorrectly), it's likely that you have an error in your usage of macros.

Was this article helpful?
How can we improve it?