This article describes how to use macros in custom creatives, especially click-through and click-tracking URLs. There are different macro variations (unescaped, escaped, double-escaped) to ensure characters are interpreted correctly when inserted into URLs. Using the wrong variation can lead to errors and users not being directed to the intended landing page.
On this page:
Technical expertise
This article is for users who develop custom creatives and requires technical expertise.
If you're a trafficker who is expected to associate a custom creative with a line item, but don't have technical expertise to troubleshoot custom creatives, find a resource who does. This might a person at your organization, who created the custom creative in Ad Manager, or a resource at a creative agency who provide your organization with the code used in the custom creative.
Macros are used in custom creatives for a variety of purposes. Two important purposes are as placeholders for destination (click-through) URLs and click-tracking URLs. These come in unescaped, escaped, double-escaped varieties.
Escaping is the practice of using one character (or a series of characters) to represent another character. URLs can only be transmitted over the internet via the ASCII character-set. However, characters outside of this set can be used in URLs, so those characters must be encoded during transmission to be interpreted correctly.
In developing custom creatives, you need to use one or more of the following in the creative code:
- Unescaped click-tracking URL:
%%CLICK_URL_UNESC%%
- Escaped click-tracking URL:
%%CLICK_URL_ESC%%
- Unescaped destination URL:
%%DEST_URL%%
- Escaped destination URL:
%%DEST_URL_ESC%%
- Double-escaped destination URL macro:
%%DEST_URL_ESC_ESC%%
To ensure that clicks are tracked or that users get to the destination URL, you need to use the appropriate variant. Using the wrong variant could mean click-tracking fails to record or that users don't reach the destination URL.
If both click-tracking and click-through URLs are required, you need to additionally ensure that the macros are sequenced or "chained" together correctly using the right variants.
In this article, you can review correct and incorrect examples of how to use destination and click-tracking URL macros and how to chain them together.
Here's an example of an unescaped click-tracking URL from Campaign Manager 360. Parameters have been removed or shortened for clarity:
http://adclick.g.doubleclick.net/aclk?sa=l&ai=C8qeK&adurl=
Compare this URL with escaped version of the same URL:
http://adclick.g.doubleclick.net/aclk%253Fsa%253Dl%2526ai%253DC8qeK%2526adurl%253D
Here, reserved characters have been double-escaped using percent-encoding. For instance, question marks (?) are always represented by the sequence of characters %253F, while the equal signs (=) are always represented by the sequence of characters %253D.
For this example, let's assume that we have a custom creative that should click through to:
http://google.com/page.html?param1=red¶m2=blue
An image creative might track clicks like the following:
<a href='
%%CLICK_URL_UNESC%%%%DEST_URL_ESC%%' target="_blank"> <img src='//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://google.com/img.gif%3Fparam1%3Dred%26param2%3Dblue' target="_blank"> <img src='//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.
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='//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://google.com/img.gif%3Fparam1%3Dred%26param2%3Dblue' target="_blank"> <img src='//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://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.
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='//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://google.com/page.html?param1=red¶m2=blue' target="_blank"> <img src='//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://google.com/page.html?param1=red¶m2=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.
Advertisers might ask you to include a third-party click tracker for their creative. A tracker keeps an independent count of clicks for a creative and helps for later auditing or reconciliation by the advertiser.
Typically, the click tracker comes in the form or a URL. Here's a Campaign Manager 360 example:
http://ad.doubleclick.net/clk;a;b;c?[click-through URL][destination URL]
The URL (ad.doubleclick.net) is a reference to the server that records the impression or click. Other third-party URL are similar. The click-through URL should be represented by two macros:
- Escaped click macro:
%%CLICK_URL_ESC%%
- Double-escaped destination URL macro:
%%DEST_URL_ESC_ESC%%
Both represent the same click-through URL and must be include after the question mark (?). Here's an example of an image creative with a Campaign Manager 360 click-tracking URL:
<a href='
http://ad.doubleclick.net/clk;a;b;c?%%CLICK_URL_ESC%%%%DEST_URL_ESC_ESC%%' target="_blank"> <img src='//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 expand the macros to their intended value. Here's an example:
<a href='
http://ad.doubleclick.net/clk;a;b;c?http://adclick.g.doubleclick.net/aclk%253Fsa%253Dl%2526ai%253DC8qeK%2526adurl%253Dhttp://google.com/page.html%253Fparam1%253Dred%2526param2%253Dblue' target="_blank"> <img src='//google.com/img.gif'> </a>
Testing ad creatives ensures that they behave as intended. Since macros are placeholders, and since there's sometimes complex code involved, the best way to test a custom creative is by previewing the creative from the line item. To do so:
- Open the creative in a new window.
JavaScript doesn't function in the preview available directly in Ad Manager. In addition, macros can't be viewed in their expanded version.
- Use your browser's development tools ("dev tools") to inspect elements and the DOM.
When the macros are inserted properly, clicking the creative from the preview leads to an Ad Manager landing page. This page confirms the click has been tracked. You are then be redirected to the destination URL page associated with the creative.
If either of these things don't happen, there's a problem with the macros or how they were chained together.
Validating impression-tracking macros requires the use of a traffic analyzer. A traffic analyzer allows to view and capture HTTP requests. Some browser dev tools include a tool of this kind. There are also third-party traffic analyzer software available.
Using a traffic analyzer, inspect the HTTP requests when the ad creative loads. You're looking for a successful request or "ping" to the server that records the impression. Note any HTTP errors during HTTP requests.
- If you don't spot any errors, and you can see a successful ping of the server that records the impression, macros have been correctly configured.
- If you spot any errors, return to the source code of your custom creative to troubleshoot. A common error code when macros are placed incorrectly is HTTP 204.
