Search Images Maps Play YouTube News Gmail Drive More »
Sign in

DFP Small Business

Rich content and third-party tags

Macro overview

What is a macro?

A macro is a short piece of code that serves as a shortcut for a message to the ad server. Macros will expand into a longer code string that the ad server can understand when they’re included in creative code or clickthrough URLs. Ad server macros are useful for passing important information to your proprietary systems or third-party ad servers. You can only insert macros in third-party creatives.

If the creative code is recognized as being from a certified vendor, then we'll automatically insert the proper macros. If we don't recognize the third-party creative code, then you'll need to insert the macros manually. You can manually insert the macro at the cursor's position in the 'Code snippet' field by clicking one of the insert macro buttons. Work with your third-party to determine where to insert the macro.

 

Click macro

A click macro allows you to track clicks on your third-party creatives. There are two types of click-tracking macros:

  • Unescaped click macro: %%CLICK_URL_UNESC%%
  • Double-escaped click macro: %%CLICK_URL_ESC_ESC%%

As a best practice, we recommend using an unescaped click macro when the creative hosted by another server is a standard image file (GIF/JPG). You should use the double-escaped click macro for Flash (SWF) creatives and for certain third parties. You can preview the ad and right-click it to determine its file type. If you see a “Save Image As...” or “Save Picture As...” option appear in the right-click menu, the creative is a standard image. If you see an “About Adobe Flash Player...” option, the creative is a Flash ad.

A small number of third parties use double escaping (%%CLICK_URL_ESC_ESC%%). For certified third parties, we’ll auto-insert this double-escaped click macro; however, if you’re unsure if you need a double-escaped macro, you should reach out to the third party for confirmation.

If you don't put a click-tracking macro in the correct place in your third-party code, you will most likely not track clicks on the creative. Talk to your third-party creative provider to learn where to put the click macro.

For more information on trafficking third-party creatives, please refer to this article.

Cache-busting (random number) macro

The cache-busting macro ensures that a fresh call is made to the ad server every time the code is executed, so you’re accurately counting impressions. Here is what the cache-busting macro looks like:

%%CACHEBUSTER%%

If you don't add the cache-busting macro to the creative code, you’re more likely to see impression counting discrepancies between DoubleClick for Publishers and a third-party ad server. Note that not all third parties require the cachebuster macro.

Most creative vendors will offer a placeholder in their tag to insert cachebuster macros. For example, if your third-party creative code contains something like this:

http://abc.3rd-party-serving.com/Targeting/adServer.php?ab=cd&e=12fg=click&ord=[RANDOM_NUMBER]

You will want to select [RANDOM_NUMBER] and click the Insert cachebuster macro button so that it replaces the placeholder:

http://abc.3rd-party-serving.com/Targeting/adServer.php?ab=cd&e=12fg=click&ord=%%CACHEBUSTER%%

If you are unsure of how to place cachebuster macros properly in your third-party creatives, please contact the vendor that created your creatives. For more information on trafficking third-party creatives, please refer to this article.

Pattern match macro

You can pass a custom variable into a creative using our creative targeting macro: %%PATTERN:key%%

Use this macro to pass targeting values into a creative. This can be helpful if you want to serve different creatives based on information you know about a user. For example, maybe you have two creatives for a given line item: one that was designed to appeal to female users and one that was designed to appeal to male users.

  1. You're passing the user's gender into an ad tag on your page via custom criteria like this: .setTargeting("gender", "male")

  2. In the third-party creative, dynamically pass the criteria using the following macro: <some creative script here>...&gender=%%PATTERN:gender%%

  3. The entire macro of %%PATTERN:gender%% will be replaced with "male".

  4. DFP will call and serve the “male” creative file to this user.

For in-stream video:

  • Expanded to the referrer URL in redirect ad tags by using the ad tag's URL query parameter, filled in by the IMA SDK. The referrer URL is the URL of the page where the video player is located.
  • Works only with the Google IMA SDK, with the following qualifications:
    • Script access must be enabled on the page for this macro to work.
    • The macro doesn't work inside an iframe.
  • Corresponds to DART's %purl=! macro.

Target window macro

The target window macro instructs the user's browser to open the creative's landing page in either the user’s existing window or a new window when the user clicks on the creative.

For example, the DFPNews.com ad unit has the target window set to _top and the DFPFashion.com ad unit has it set to _new. If the %%TARGET_WINDOW%% macro is included in the creative's code or script, it will open a new window when a user of DFPFashion.com clicks on it and an existing window if a user of DFPNews.com clicks on it.

Typically, here’s where you’d see %%TARGET_WINDOW%% placed in the creative code:

<a href="%%CLICK_URL_UNESC%%%%DEST_URL%%" target="%%TARGET_WINDOW%%"><img src="my ad"></a>

Related