DoubleClick for Publishers

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.

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

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

This macro can be helpful if you are trafficking a custom creative and you want the click-through URL that you set in the creative trafficking screen to override the click-through URL built into the custom creative code.

There are three URL macros you can use:

• %%DEST_URL%%
• %%DEST_URL_ESC%%
• %%DEST_URL_ESC_ESC%%

Normally the amount of escaping (whether you include ESC once, twice, or not at all) depends on the third-party click-tracking company. Some third-party click-tracking companies require the URL to be escaped, while others do not.

The level of escaping required by a third-party click-tracking company is normally specified in the tag with the click= string in the third-party ad tag or custom creative code in DFP:

• click= escape it once (%%DEST_URL_ESC%%)
• click1= escape it once (%%DEST_URL_ESC%%)
• click0= don't escape it (%%DEST_URL%%)
• click2= escape it twice (%%DEST_URL_ESC_ESC%%).

This macro is most commonly used to track line items with your backend reporting system. %e is used in combination with match tables, which provide a relationship between the ID number in the database and the ID number in DoubleClick for Publishers. This can be useful for troubleshooting; for example, a trafficker only has to look at the ad server response in order to see the line item ID or creative ID that served to an ad tag.

You insert the %e macro at the end of the ad's clickthrough URL in its creative assignment (for example: http://www.firstautomobile.com/?%ecid!; inserts the creative ID for the line item).

The different expand macros available are:

• %eaid! -- expands with line item ID
• %ecid! -- expands with the creative ID
• %eenv! -- expands with the environment (tag type) indicator. For example, 'i' if iframe, 'j' if JavaScript, etc.
• %esid! -- expands with the first-level ad unit ID serving the line item
• %epid! -- expands with the ID of the lowest level ad unit in the tag
• %eadv! -- expands with the advertiser ID of the line item being served
• %ebuy! -- expands with the order ID of the line item being served

The %e macros can be separated from one another in the clickthrough URL with any character that is safe for use in DFP clickthrough URLs: http://www.site.com/?%eaid!;%ecid! could become: http://www.site.com/?1234567;4265598

The file server macro is an ad server macro most commonly used as a shortcut to designate a creative file's path on DoubleClick's global creative and media servers. Here's what it looks like: %%FILE:file_display_name%% where file_display_name is the display name you give to the creative file in DFP.

In general, the file server macro will be replaced with the machine name for a physical ad server when an ad serves. This is particularly beneficial for line items that are served to multiple countries.

The geo ad server macro, %g, can be used in the click-through URL, the redirect URL, and the custom code of a creative. This macro is used to track geographic information - country code, state or province, telephone area code, postal code, bandwidth, and DMA (Designated Marketing Areas) - using your proprietary systems, after a website visitor clicks an ad served by DoubleClick for Publishers. This macro can be implemented regardless of whether a line item has been geographically targeted.

When %g expands into a string, it displays the geographical information of the user to whom the ad was served - assuming that the user's IP address can be looked up - as shown here:

ct=US&st=CA&city=13358&dma=197&zp=94105&bw=0

where:

• ct is the key that returns a value for a country code
• st is the key that returns a value for a U.S. state, territory, or Canadian province
• city is the key that returns a value for a city
• dma is the key that returns a value for designated market areas
• zp is the key that returns a value for a postal code
• bw is the key that returns a value for bandwidth

The string is always expanded in the order shown above.

The %%HEIGHT%% and %%WIDTH%% macros insert the creative height and width into the custom code of a creative during the ad serving process, based on the size of the ad slot where the creative is being served.

These macros can be especially useful if you're creating a creative template that you want to reuse with creatives of different sizes. Instead of hard-coding the size for each creative, you can let the height and width macros insert the values into each creative dynamically.

You can also use these macros in the custom code for creatives where you've overridden the creative size (which you can do on the "Settings" tab of a creative). When you override the size, you can enter multiple creative sizes. The creative can then be served to ad units of any of those sizes. You can use the height and width macros to add the dimensions dynamically to the creative code when the creative is served.

The host name ad server macro, %a, can be used in the redirect URL and custom code of a creative. This macro expands into http://pubads.g.doubleclick.net.

The interstitial impression macro enables the DFP ad server to record when an interstitial impression is served from a creative that wasn’t built using one of the built-in creative templates for pop-ups, pop-unders, and floating Flash overlays.

Use %%VIEW_URL_UNESC%% for image creatives (JPG, GIF) and %%VIEW_URL_ESC%% for Flash creatives (SWF).

Here's an example of the proper implementation:

<img src=%%VIEW_URL_UNESC%%http://www.acme.com/img/logo.gif>

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:

   GPT tag:

   googletag.defineSlot("/1234/adunit1/adunit2", [728, 90],
   "div-gpt-ad-123456789-0")
   .addService(googletag.pubads())
   .setTargeting("gender", "male");

   DART tag:

   http://ad.doubleclick.net/ad/sitename/pagename;gender=male;ord=12323

2. In the custom or 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.

The site name ad server macro, %s, can be used in the click-through URL, the redirect URL, the custom code of a creative, and click commands. This macro is commonly used to track the name of the site (included in the ad tags) where visitors clicked on an ad served by DART in a proprietary system. This macro expands into the originating site's name as defined in DART, not into the DNS name of the site.

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>

To ensure that query parameters in creative templates are transformed properly, use the URI encode macro when you create the creative template. For instance, you would use the macro when a creative template variable is used as a query parameter or when a URL in a creative template is used as a query parameter. The following sections show you how.

When creative template variables are used as query parameters

The URI encode macro allows creative template variables to be used as query parameters. This macro is only available for creative templates and cannot be used in creatives in which you can add code snippets such as custom creatives or third-party creatives. Take the following example:

Imagine a creative template has a list variable "Flavor", which is for an ice cream flavor, with the possible values "chocolate fudge brownie", "rum raisin", etc.

In this example, the creative template formatter includes the following:

<a href="http://icecreamflavors.com/interested-in-flavor.php?flavor=[%Flavor%]">Click me!</a>

The "flavor" variable must be properly URI encoded or the click-through URL will end up containing spaces:

http://icecreamflavors.com/interested-in-flavor.php?flavor=chocolate fudge brownie

Note the spaces in the value for "flavor". This URL will not work.

To prevent this from happening, enter the the following in the creative template formatter: [%URI_ENCODE:variable%]. Then specify the values of variable. In our example, you would enter chocolate fudge brownie, rum raisin, etc.

Note that the spaces in the value for "flavor" have been replaced with %20 in the below URL. The following URL will work:

http://icecreamflavors.com/interested-in-flavor.php?flavor=Chocolate%20Fudge%20Brownie

When URLs in creative templates are used as query parameters

Another case in which using the URI encode macro is important is when passing a template variable as a redirect URL to the click server. Suppose you have the following code in your template:

<a href="%%CLICK_URL_UNESC%%[%ClickThroughUrl1%]">Click me!</a>

If the value of ClickThroughUrl1 contains query parameters (?k1=v1&k2=v2), the URL becomes malformed and the redirect won't work as it should. For example, if it contains an ampersand (&), it will be attributed to the full URL and not the redirect URL. To ensure the URL is correctly formed, then in the creative template formatter specify the ClickThroughUrl1 with the URI encode macro: <a href="%%CLICK_URL_UNESC%%[%URI_ENCODE:ClickThroughUrl1%]">Click me!</a>