DFP macros

In DoubleClick for Publishers, macros are strings of text that the DoubleClick ad server replaces with other strings of text according to a set of rules. They can be included in any code that's processed by the ad server during the delivery process: third-party or custom creative code, DoubleClick Rich Media code, click-through URLs, DFP tags, even within Flash files that are hosted by DFP.

For each macro, we've provided suggestions on how you might use it. However, how you use macros is up to you. Like the DoubleClick for Publishers API, macros can be put to whatever uses are most valuable for you.

Macros are case-sensitive. For example, %%CACHEBUSTER%% works, but %%Cachebuster%% doesn't.

 

Add macros to creative code

One of the main uses of macros is within the creative code of custom and third-party creatives. For third-party creatives, if DFP recognizes the third party, it inserts the macros automatically. For custom creatives and creative templates, you need to add the macros manually.

 

Supported macros

DoubleClick for Publishers supports the following macros. We've grouped them according to their most common uses, but macros are highly flexible tools that you might use differently.

 

Rendering macros

These macros are most commonly used in the process of rendering creatives, ensuring that they look right and work correctly.

Destination URL macro

Macro Escaping
%%DEST_URL_ESC%% Escaped
%%DEST_URL_ESC_ESC%% Double-escaped
%%DEST_URL_UNESC%% Unescaped

The destination URL macro expands to the creative's click-through URL, which is either the line item's click-through URL or an override set for the creative within the line item.

The destination URL macro is useful in custom creatives and creative templates. If the creative code needs to include the creative's click-through URL, and the click-through URL changes as the creative or template is used across different line items, then this macro can help.

There are three click-through URL macros: escaped, double-escaped, and unescaped. Typically 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 often 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%%).

  • click0=: Don't escape it (%%DEST_URL_UNESC%%).

  • click1=: Escape it once (%%DEST_URL_ESC%%).

  • click2=: Escape it twice (%%DEST_URL_ESC_ESC%%).

DFP also supports %%DEST_URL%%, which does exactly the same thing as %%DEST_URL_ESC%%. We recommend using %%DEST_URL_ESC%% for clarity, but there's no need to recode older creatives and templates.

File server macro

Macro
%%FILE:file_display_name%%

The file server macro %%FILE:file_display_name%% can be used within the code of a custom creative. It expands to the full URL of a creative asset that has been uploaded to the creative. It can be useful if your custom creative code needs to call the asset.

To use the macro, replace file_display_name with the display name of the creative asset, as it's shown in DFP when you view the creative details.

Height and width macros

Macro
%%HEIGHT%%
%%WIDTH%%

These macros insert the creative height and width into the custom code of a creative during the ad serving process.

The height and width 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.

Pattern match macro

Macro
%%PATTERN:key%%

Use the pattern match macro to pass a custom variable such as a targeting value into a creative. This can be helpful if you want to serve different creatives based on information you know about a user, such as a user's content preferences.

For example, 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. Here is how the process works:

  1. You're passing the user's gender into an ad tag on your page via custom criteria:

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

Target in new window macro

Macro
%%TARGET_IN_NEW_WINDOW%%

The target in new window macro expands to a value that corresponds to the target window specified for the publisher and ad slot where an ad is being served:

  • If the target window is _blank, the macro expands to 1.

  • If the target window is any other value, or if no target window is specified, the macro expands to 0.

Target window macro

Macro
%%TARGET_WINDOW%%

The target window macro expands to the target window specified for the ad unit where a creative is being served. You can use the macro within the code of a creative to specify whether a click on the creative will take the user to a new window or load the landing page in the same window, depending on the settings for each site where users will see the ad.

For example, the DFP_News.com ad unit has the target window set to _top and the DFP_Fashion.com ad unit has it set to _new. If the %%TARGET_WINDOW%% macro is included in the creative's code, it will expand to _top for users at DFP_Fashion.com and _new for users of of DFP_News.com.

Here's an example implementation:

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

Tag for child-directed content macro

Macro
%%TFCD%%

The tag for child-directed content (TFCD) enables you to let third parties know that a given ad request comes from a page with child-directed content. The macro is intended to assist in compliance with the Children’s Online Privacy Protection Act (COPPA).

You can include the macro in any redirects or requests for third-party creatives, in the format coppa=%%TFCD%% or something similar. It can also be used in JavaScript to set GPT passback tag requests for child-directed treatment. The macro expands to 1 for child-directed content, or 0 for other content, based on information about the nature of the page, site or mobile app that sent the request to DFP.

If you are using Google's advertising services and would like to implement child-directed treatment at the site or app level, please see Tag a site or app for child-directed treatment.

URI escaping macro

Macro
[%URI_ENCODE:variable%]

The URI escaping macro can ensure that values that are inserted into URIs are formatted correctly, with all of the necessary escaping of characters such as spaces. For example, if you're dynamically adding query parameters to a URL, and some of those query parameters contain spaces, you can use the URI escaping macro to ensure that the query values are formatted into valid strings for a URL.

This macro only works with creative templates, not with custom or third-party creatives.

Use creative template variables as query parameters

The URI encode macro allows creative template variables to be used as query parameters.

For example, 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. The creative template formatter includes the following code:

<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, which doesn't work:

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

To prevent this from happening, enter [%URI_ENCODE:variable%] in the creative template formatter. Then specify the values of variable. In our example, you would enter chocolate fudge brownie, rum raisin, etc. The result is that the spaces in the variables get escaped, replaced with %20, resulting in a URL that works:

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

Use creative template variables as redirect URLs

To ensure proper URL formatting, use the URI escaping macro when passing a template variable as a redirect URL.

For example, you have the following code in your template:

<a href="%%CLICK_URL_UNESC%%[%click-throughURL1%]">Click me!</a>

If the value of click-throughURL1 contains query parameters (?k1=v1&k2=v2), the URL becomes malformed and the redirect won't work as it should. In this example, the content after the ampersand (&) will be attributed to the full URL rather than the redirect URL. To ensure that the URL is correctly formed, in the creative template formatter, specify the click-throughURL1 variable with the URI encode macro: <a href="%%CLICK_URL_UNESC%%[%URI_ENCODE:click-throughUrl1%]">Click me!</a>

 

Tracking macros

These macros are primarily or most commonly used for tracking and reporting purposes.

Cachebuster (random number) macro

Macro
%%CACHEBUSTER%%

The cachebuster macro ensures that a fresh call is made to the ad server every time the code is executed, so you’re accurately counting impressions. 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 cache-buster 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.

Click macro

Macro Escaping
%%CLICK_URL_ESC_ESC%% Double-escaped
%%CLICK_URL_UNESC%% Unescaped

A click macro allows you to track clicks on third-party creatives.

As a general rule, use an unescaped click macro when the creative hosted by another server is a standard image file (GIF/JPG). Use the double-escaped click macro %%CLICK_URL_ESC_ESC%% 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 certified third parties, DFP auto-inserts the right click macro. If you’re unsure which click macro to use or where to place it within the creative code, ask the third party for confirmation. Incorrectly placed click-tracking macros probably won't track clicks.

Do not enter the click macro as the source of an image or iframe. Doing so results in a click being recorded every time the image or iframe renders, which is not legitimate and is filtered out as an invalid click.

To check whether your creative is tracking clicks properly:

  1. Preview the creative.

  2. Click on the preview. If clicks are being recorded, DFP displays a message letting you know. If you don't see that message, then the click macro isn't working correctly in your creative.
DFP also supports %%CLICK_URL%% and %%CLICK_URL_ESC%%, which do exactly the same thing as %%CLICK_URL_ESC_ESC%%. We recommend using%%CLICK_URL_ESC_ESC%% for clarity, but there's no need to recode older creatives and templates.

 

Viewed impression macro

Macro Escaping
%%VIEW_URL_ESC%% Escaped
%%VIEW_URL_UNESC%% Unescaped

The viewed impression macro enables DFP to count an impression when a creative is viewed rather than when it's served. It's used primarily for interstitial or similar creatives. It's included automatically in the code for some built-in pop-up and pop-under creative templates, and you can add it to the code of custom templates as well. It expands to a URL that contains the information DFP needs to record the impression.

This macro works in conjunction with signals in the ad tag that let DFP know not to count the impression immediately:

  • GPT tags that include d_imp=1 for delayed impressions.

  • DART tags that include /pfad, /pfadi, /pfadj, or /pfadx for prefetch ads, or 1_ist= or ist= for interstitial ads.

If the creative is served to tags that don't include one of these signals, DFP expands the macro to "".

Expand macros

Macro What it expands to

%eaid!

Line item ID

%eadv!

Advertiser ID for the line item being served

%ebuy!

Order ID for the line item being served

%ecid!

Creative ID

%eenv!

Environment (tag type) indicator: i for iframe, j for JavaScript

%epid!

ID of the ad unit where the line item is being served

%esid!

ID of the highest-level ad unit above the ad unit where the line item is being served

The expand macros can be used within custom creative code or in a click-through URL. They're most commonly used to track line items with your backend reporting system. You can match the IDs from DFP with IDs in your own database. The information you store in this way can be useful for troubleshooting.

You can insert the expand macro at the end of the line item's click-through URL (or the click-through URL for the creative, if you're overriding the line item's URL). For example, http://www.firstautomobile.com/?%ecid! inserts the creative ID for the line item.

Expand macros can be separated from one another in the click-through URL with any character that is safe for use in DFP click-through URLs. For example, http://www.site.com/?%eaid!;%ecid! might expand to http://www.site.com/?1234567;4265598.

Preview mode macro

Macro
%%PREVIEW_MODE%%

You can use the preview mode macro in custom creative code to prevent counting of preview impressions by your backend systems or third-party systems. The macro expands to true if the creative is being viewed as a DFP preview, false if it's a regular impression.

Scheme macro

Macro
%%SCHEME%%

The scheme macro expands to http:// or https://, whichever matches the security scheme of the webpage where a creative is being served. You can put it at the beginning of a URL:

<img src=%%SCHEME%%www.website.com/img/logo.gif>

Site macro

Macro
%%SITE%%

Expands to the domain of the URL parameter in an ad tag (for example, google.com). The macro be used to modify your creative based on where the request came from. It doesn't work on AdExchange ads that are marked as anonymous.

 

Video-specific macros

Many publishers require access to referrer URL, content URL, and other video information such as video ID and duration as ad server macros. DoubleClick for Publishers supports the ad server macros detailed below for video.

Your DFP network must be connected to a content source for some of these video-specific macros to expand properly, since DFP obtains the values from ingested content metadata.

Video description URL macro

Macro Description and requirements

%%DESCRIPTION_URL%%

In redirect ad tags, expands to the description URL parameter from the original GPT ad tag's description_url query parameter. The description URL should typically be the same as the referrer URL. You should specify the description_url on the GPT ad tag if there are embeds where the IMA SDK might not accurately detect the page URL, or if you are using video in Ad Exchange or AdSense for Video.

Video duration macro

Macro Description and requirements

%%VIDEO_DURATION%%

Expands to the duration of the video in milliseconds.

Content ingestion is required for this macro to work.

Video ID macro

Macro Description and requirements

%%VIDEO_ID%%

Expands to the ID of the video content currently playing, which is the unique ID in the CMS or the dfpvideo:ContentID value from mRSS.

Content ingestion is required for this macro to work.

Video metadata macro

Macro Description and requirements

%%VIDEO_METADATA:key%%

Expands to metadata about the video where the creative is being served, based on key-values associated with the video content. The key-values are set up in DFP in the "Video" tab.

Content ingestion is required for this macro to work.

Video referrer URL macro

Macro Description and requirements

%%REFERRER_URL%%

Expands 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. It 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.

  • Requires the use of Google Publisher Tags.

Video title macro

Macro Description and requirements

%%VIDEO_TITLE%%

Expands to the title of the video.

Content ingestion is required for this macro to work.