Macros for custom creatives

Lean to use escaped and unescaped macros

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.

Example macro insertions

Here's an example of an unescaped click-tracking URL from Campaign Manager. 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.

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: third-party click trackers and macros

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 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 a simple image creative with a Campaign Manager click-tracking URL:

<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 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://www.google.com/page.html%253Fparam1%253Dred%2526param2%253Dblue' target="_blank"> <img src='//www.google.com/img.gif'> </a>

Creative preview and testing macros

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:

  1. 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.

  2. Use your browser's development tools ("dev tools") to inspect elements and the DOM.

Validate click-tracking macros

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. 

Validate view macros

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.
Was this helpful?
How can we improve it?