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.

Escaped, double-escaped, and unescaped URL macros

URL macros such as destination URL, click macro, viewed impression macro, and some video-specific macros, are available in unescaped and double-escaped variants. It's important to understand when to choose the right variant of these macros. For this reason, we recommend reading the article on escaped vs. unescaped URL macros.

For clients that have upgraded from DART for Publishers

DoubleClick for Publishers uses different macros from DART for Publishers, and legacy macros may work differently for campaigns that you traffic in DoubleClick for Publishers. For campaigns that were fully trafficked in legacy DART for Publishers and are being served to DART tags, macros will continue to work as expected.

Current and legacy macro comparison

The table below lists legacy DART for Publishers macros and explains how they work with DoubleClick for Publishers. It also lets you know whether there's a new macro in DoubleClick for Publishers that replaces the DART macro. We strongly encourage you to use new DoubleClick for Publishers macros for all new creatives, creative templates, and other implementations.

Macro Name New macro How the legacy macro works with DoubleClick for Publishers

%a

Host name

Expands into http://pubads.g.doubleclick.net.

%c

Click

Works the same as a double-escaped DoubleClick for Publishers click macro.

%e

Expand

The various expand macros will show the IDs of entities connected with the line item and creative being served and the ad unit to which it's being served. The inventory hierarchy in DoubleClick for Publishers is different from the hierarchy in legacy DART for Publishers, so the way the expand macros identify inventory is also different.

The %e expand macros are fully supported in DoubleClick for Publishers, as described below.

%g

Geo

Works the same as in legacy DART for Publishers. However, the geographic data used for expanding this macro is no longer updated and may be out of date. Values for area codes, postal codes, DMAs, and even some countries may have changed.

%h

File server

Only works for creatives trafficked in legacy DART for Publishers.

%i

Viewed impression

Works the same as an unescaped viewed impression macro. However, there is no automatic ad deactivation in DoubleClick for Publishers when the viewed impression macro is not included in the creative code for interstitials.

%k

Keyword

Not supported with Google Publisher Tags.

%m

Match code

Not supported.

%n

Cache-busting (random number)

Works the same as the DoubleClick for Publishers cache-busting macro.

%p

Pattern match

Not supported with Google Publisher Tags.

%s

Site name

Expands to the name of the highest-level ad unit above the ad unit where the line item is being served.

%t

Target window

Works the same as the DoubleClick for Publishers target window macro.

%u

Destination URL

Works the same as the escaped DoubleClick for Publishers destination URL macro.

 

Legacy DART for Publishers macros in detail
This section provides information from the legacy DART for Publishers help. It does not describe the current functionality of these macros in DoubleClick for Publishers. Rather, it describes how they worked in legacy DART for Publishers.

Quick reference of ad server macros

This table lists ad server macros supported by DART and identifies where you can use them.

Table 2: Ad server macros in DART

Macro

Name

Purpose

Click-Through URL

Redirect URL

Custom Creatives

Click Command

%a

Host name

Expands into the host name sent by the browser in the ad request; see Inserting the host name using %a.

 

 x

 x

 

%c

Click

Inserts the click-through URL; see Tracking clicks using %c.

 

 x

 x

 

%e
<key>

Expand attributes

Inserts the attributes specified by the key that follows the macro; see Using %e to include attributes.

 x

 x

 x

 x

[subset]

%ebuy

Expand attributes

 

 

 

 

 

%g

Geo

Tracks geographic data post-click; see Tracking geographic data using %g.

 x

 x

 x

 

%h

DART server

Inserts the URL of the server that serves the creative. This can be a media server or a DART ad server; see Specifying an ad server using %h.

 

 x

 x

 

%i

Impression string

Expands into an impression string so that the ad served to a user can be tracked; see Inserting an impression string using %i.

 

 x

 x

 

%k

Keyword

Captures a user-entered string; see Inserting keywords into text of a creative using %k.

 x

 

 x

 

%m

Match code

Expands the DoubleClick user ID (cookie) for use in demographic targeting; see Implementing match codes using %m

 x

 

 

 x

%n

Random number

Inserts a random number to defeat caching; see Inserting a random number using %n.

 x

 x

 x

 

%p

Pattern match

Captures a string within an ad request and passes it into a URL; see Inserting search words into text of a creative using %p

 x

 x

 x

 

%s

Site name

Inserts the site name (defined in DART and used in ad tags) of the originating site; see Inserting a site name using %s.

 x

 x

 x

 x

%t

Target window

Instructs the user's browser to open a target window when the ad is clicked; see Using %t to specify target window.

 

 

 x

 

%u

Click-through URL

Inserts the ad's default click-through URL; see Using %u to insert a URL

 

 

 x

 

Inserting the host name using %a

The host name ad server macro, %a, can be used in the redirect URL and custom code of a creative. This macro expands into the host name sent by a browser in the Host field of an HTTP request for an ad. For example, if an ad request includes:

http://ad.co.doubleclick.net/...

then ad.co.doubleclick.net is the host name used by this macro.

Tracking clicks using %c

The click ad server macro %c can be used in the redirect URL and the custom code of a creative. This macro is frequently used; it tracks clicks on a custom creative by inserting a click string on an ad that otherwise could not be tracked.

The %c is inserted before the click-through URL of the creative. In an HTML creative, %c is added to the beginning of all action and href attributes. In a JavaScript creative, add the ad server macro %c to the option URL. Do not use %c in both the action and option URLs, because the click would be counted twice.

The format of this macro is (the :// is escaped in this example, see the note below):

http%3A%2F%2ad.doubleclick.net/click;361119;0-8388608;2;321977;1-468|60;0|0|0;;?

The characters :// must be replaced with the ASCII equivalent %3a%2f%2f in URLs when %c is used. This ensures that the code can be translated by any browser.

An example of a form with an action attribute and the %c macro is:

<form action="%chttp%3a%2f%2fwww.advertiser.com" method="get">

Method="get" vs. method="post": Some custom creatives use the method attribute to redirect a user when he or she clicks on a creative. Method is an attribute of the <form> tag, which tells the browser how to send data contained in the <form> tag. There are two common values of method which are used in HTML custom creatives that contain the <form> tag:

  • method="get" sends the information to the server specified in the action attribute of the <form> by appending data to the end of the click-through URL.
  • method="post" also sends information to the server specified in the action attribute of the <form>; however, method="post" sends information in the body of the new HTML page, rather than in the URL, therefore %c cannot track clicks.

Because %c passes information to the DART ad servers via the URL, it can only be used in combination with method="get". Therefore, the code on the advertiser's webpage - where the user arrives postclick - must be able to retrieve data using method="get".Verify that the contact person at the advertiser or agency uses method="get" when developing creatives.

Using %e to include attributes

The expand attributes ad server macro, %e, can be used in the click-through URL, the redirect URL, the custom code of a creative, and click commands. It is used for multiple event tracking of Rich Media (formerly Motif) ads. By using one of the macro extensions, you can dynamically insert a value (an integer) from the DART database into the URL or custom code of an ad. Then, you can use a match table to associate the database value to the description of the entity.

For example, one of the values that you can specify in an extension is the pageID (pid) which corresponds to the ID of a zone where DART delivers an ad.

A click-through URL can contain multiple %e macros separated by the character of your choice: semicolons, slashes, or ampersands as shown here:

http://www.site.com/?%eaid!;%esid!;

For each %e in a URL, the ad server dynamically inserts a value from the DART database, based on the key that follows the %e macro, in the format of %e<key>! where <key> can be any of the values listed in this table.

Table 3: Keys that can be used with the %e ad server macro

Key Attribute Inserted Click Command

aid

Ad ID of an ad served

 x

pid

Zone ID where an ad is served

 x

sid

Site ID where an ad is served

 x

rid

Rendering (or creative) ID of a creative delivered

 x

cid

Creative ID of a creative delivered

 x

kid

Key-value ordinal that was matched by the ad servers when choosing an ad to serve

 

adv

Advertiser ID of an ad that is served

 

env

Environment character, which specifies the type of ad slot (/, f, i, j, l, or x)

  • / - standard image-based ad
  • f - in a frame
  • i - in an iframe
  • j - using JavaScript
  • l - in a layer
  • x - using streaming technologies.

 

rv

Rendering version, which is the version of a creative that is delivered

 

buy

Buy or order ID of an ad served

 x


You cannot use the %e macro in a ad with click commands that runs on a DART for Publishers site. Certain values - advertiser ID and page ID for example - populate with the DART for Publishers values instead of the the DART for Advertisers values that you might expect.

Tracking geographic data using %g

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 user clicks an ad served by DART. This macro can be implemented regardless of whether an ad 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=NY&ac=212&zp=10011&bw=1&dma=1

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
  • ac is the key that returns a value for a telephone area code
  • zp is the key that returns a value for a postal code
  • bw is the key that returns a value for bandwidth
  • dma is the key that returns a value for designated market areas

Specifying an ad server using %h

The DART server name ad server macro, %h, can be used in the redirect URL and the custom code of a creative. This macro expands to the address of the DART ad or media server. Using %h rather than hardcoding the URL of the ad servers automatically serves the ad from the ad server closest to the user rather than always retrieving the creative asset from a location that you specify manually. The macro inserts the appropriate secure server and country code, usually a media server, whereas hard coding host names forces an ad server to deliver the creative which is not usually the optimal choice.

You should use %h in all custom creatives that are hosted by DART servers. Similarly, you should use %h instead of hard coding the host name into every URL that links to files hosted by DART. For example, you can use %h in the following Java creative that requires you provide the complete path to an asset.

Instead of:

<img border="0" src="http://ad.doubleclick.net/AdvertiserID/filename.gif" width="x" height="y" alt="Alternative Text">

you can use:

<img border="0" src="%h/AdvertiserID/filename.gif" width="x" height="y" alt="Alternative Text">

DART uses IP-based data supplied by digitalEnvoy for geographical targeting. The accuracy of this information is limited by ISP proxy servers.

Inserting an impression string using %i

The impression string ad server macro, %i, is used to track impressions of custom ads. This macro must be used in all interstitial ad types because it enables the DART ad servers to record when the interstitial impression actually displays. If the macro is not included, DART deactivates the ad.

The %i macro must be placed:

  • Before the URL of the source attribute of the image or JavaScript HTML tag
  • Within an active portion of the code that will be called consistently
  • Only once within the creative code

The %i macro will not accurately count impressions if:

  • Placed within a non-active portion of the code, such as between <noscript> tags in a JavaScript creative. Impressions are not counted every time a creative displays. Undercounting impressions towards one creative will affect frequency cap behavior.
  • More than one %i macro is within the creative code. Even if there are multiple image or script tags, the %i macro should only be inserted in one of them. A separate impression will be tracked for every %i macro included in the code. Counting multiple impressions towards one creative will affect frequency cap behavior.

When the browser calls the URL containing the %i macro, it expands to an impression string with a format similar to a click string:

<ver_str>;<tag_env_letter>;<id>;<imgSeries[-creativeID]>;<kv>;<pageID>;<W|H>;<creativeID|renderingID|renderVer>;<u=>;[feederAdImpString];cs=<check_sum>

For example, the HTML <img src=%ihttp://www.acme.com/img/logo.gif> expands to:

<img src=http://ad.doubleclick.net/imp/v1;f;1857347;0-0;0;1772804;468|60;0|0|0;;cs=n?http://www.acme.com/img/logo.gif>

Inserting keywords into text of a creative using %k

The keyword ad server macro, %k, can be used in the click-through URL and the custom code of a creative. This macro dynamically inserts user-enter keywords or key-values into the text of a creative. This macro is useful for ads targeted to multiple keywords and custom ads that interactively insert the text of a user's keyword search.

For example, if an ad is keyword-targeted to both "Car Insurance" and "Car Loans," the same custom ad can display "Click here for Car Insurance" for a user who searches on car insurance and "Click here for Car Loans" for a user who searches on car loans.

This macro is similar to the %p ad server macro in that it captures a substring designated by parameters that define where a keyword string starts and ends:

%k<start_key_string>!<end_char>

The benefit to using %k is that it replaces escaped characters, such as the plus sign (+), with its original character. That is, all escaped characters within the captured substring are automatically unescaped, or converted back to their original character sets. For example, when you book the keywords: kw=car+loan, you do not want the plus sign (which is escaped by DART) to display in the ad. By embedding %k in the custom code, the ad server can take the string kw=car+loan, strip out the + and replace it with the space character to display it as Car Loan in the ad.

Syntax of %k: The following example shows how you use the %k ad server macros.

%k=<start_key_string>!<end_char>;!^en;

where:

%kis the ad server macro.
<start_key_string>is the key-portion of the key-value pair. These characters must be included in the DART ad tag.
!delimits the starting string from the ending character string.

where:

<end_char>character that ends the key-value.
;identifies the end of the macro

One difference between the %k and %p macros is that %k inserts text into the HTML of the webpage, while %p inserts strings into the click-through URL; therefore, %p is useful for recording information about the click.

Truncating or abbreviating strings: Long keyword strings can be abbreviated using the macro extension ^n, which truncates the string at the nth character after the end character of the %k string.
For example:

<a href=http://www.advertiser.com>Click Here for %kkw=!;^8</a>

crops the string at the eighth character.

You can also truncate a string and appended ellipses to the truncation. For example:

<a href=http://www.advertiser.com>Click Here for %kkw=!;^e8</a>

To do this, use the extension ^en with %k. The ad server truncates the string at n-3, which is after the number of characters represented by n minus three for the three dots of the ellipses. For example, ^e11 crops the string at the eighth character and adds the three dots of the ellipses for a total of 11 characters.

Implementing match codes using %m

The match code ad server macro, %m, can be used in the click-through URL of a creative and in custom creative code.

This macro inserts the user's DoubleClick cookie ID into a click event. For users who do not accept DoubleClick cookies or have opted out of cookies, the ad servers do not expand %m.

This match code macro enables you to leverage proprietary data to track the DoubleClick user ID for users who click an ad served by DART and then generate a list of user IDs for use with Boomerang targeting.

Inserting a random number using %n

The random number ad server macro, %n, can be used to insert a random number in the clickthrough URL, the redirect URL, and the custom code of a creative. This random number macro is most often used in situations where a DART ad redirects to a third-party server for a creative. Rather than sending the browser a URL that can be cached, the ad servers dynamically generate a random number and append it to the URL using %n. This macro defeats caching and prevents undercounting of impressions from third-party ad servers, and also enables the third party to track clicks.

Third-parties typically have their own random number syntax, similar to that used by DART: ord=<random>. You should always confirm with the third party that they support this additional character string.

Inserting search words into text of a creative using %p

The pattern match ad server macro, %p, can be used in the click-through URL, the redirect URL, and the custom code of a creative. This macro dynamically inserts user-entered search words into the text of a custom creative. This ad server macro can capture any string within the URL (that is, the ad request) that contains the search terms sent back to the user. This macro is similar to the %k macro (which uses the kw= attribute) except that the %k macro replaces escaped characters, while the %p macro uses the user-defined key=value attribute.

This macro can also be used to create unique URLs. In certain situations, you could have a special click code to append to the click-over URL for each site and banner type that is run. Without using %p, a separate ad per click code would need to be created.

The %p macro is used with user-defined key-value pairs that are inserted into the DART tags before they are sent out to the sites. The value of the key-value pair can be any string of ASCII values, not less than two characters in length, that you would like returned except for a semicolon because it is used as a delimiter in tags.

For example, the %p macro can be used to specify the city for the following ad:
http://ad.doubleclick.net/ad/sitename/pagename;city=119;ord=12323

Using city= as the start_key_string and ; as the end_char, you can enter the click-through URL in the ad placement as follows: "http://www.site.com/asp?city=%pcity=!;"

The ad server expands the click-through to: "http://www.site.com/asp?city=119"

If the end_char cannot be found in the ad/jump tag (because the city= is the last key-value in the tag), then the ad server copies the whole string starting from "city=" to the click-through URL. This is a common mistake. Be sure to use an ending character.

Like %k, this macro is useful for ads that target multiple keywords and for custom ads that display a searched keyword; see Inserting keywords into text of a creative using %k.

The %p macro captures the string designated by the parameters start_key_string and end_char:

%p<start_key_string>!<end_char>

It also inserts strings into the click-through URL so is useful for recording information about the click.

Truncating and abbreviating strings: Long keyword strings can be abbreviated using the macro extension ^n with %p. To abbreviate strings after a given number of characters, insert the macro ^n after %p, where n is a number of characters. Like %p, you can also add ellipses to the abbreviated string by using the combination ^en; see Truncating or abbreviating strings.

Inserting a site name using %s

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 site name (included in the ad tags) where users 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.

Using %t to specify target window

The target window ad server macro, %t, can be used in the custom code of a creative. This macro inserts the target window value specified in the Target Window field in the General tab of a site in DART for Publishers.

The target window specifies the window where the click-through webpage is displayed when a user clicks the custom ad. Using %t rather than hardcoding enables you to dynamically insert the settings for each site, rather than having to rewrite the custom creative based on the site's settings. For example, instead of using the "_top" as the value of target=, as shown here:

<form target="_top" action="http://www.advertiser.com" method="get">

You could enter "%t" instead:

<form target="%t" action="http://www.advertiser.com" method="get">

For example, if Site X configures the target window as "_top" and Site Y configures it as "_new", then an ad that uses %t in the custom code or script displays at the top of the site if it is served to Site X and opens a new window on click-through if it is served to Site Y.

Using %u to insert a URL

The click-through URL ad server macro, %u, can be used in the custom code of a creative. This macro inserts the ad's click-through URL specified in the assignment into the code of a custom creative (Clickthrough URL field of the Ad Properties). This macro is useful because other ad server macros can be embedded within a click-through URL, and click-through URLs can be changed without modifying thecustom code.

For example, you can include the %c ad server macro to track clicks if necessary. When %u expands into the click-through URL, then any other macros in the click-through URL automatically expand as well.

For example, in the Click-Through URL field of the custom ad, you enter:

http://www.adv.com/promo/?%pid=!;&%esid!&sc=dclk

Then, in the HTML code of the creative, instead of having to copy the whole string again you can enter this:

<a href="%c%u">

In a JavaScript creative:

function clickThrough(searchTerm){location.href="%chttp%3a%2f%2f%www.advertiser.com";}

can be changed to: function clickThrough(searchTerm){location.href="%u";}

The ad server macro %u cannot be used in creatives with more than one click-through URL.

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.

View all macro descriptions   Collapse all macro descriptions

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.

%%PATTERN:url%%

You can also use the reserved key url to expand to the URL of the referring page. Note that url is a reserved key; any custom targeting values in your DoubleClick tags that have url as the key name will be overwritten with the referrer URL.

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.

Note that the macro will not double-encode characters that have already been encoded. For example, a period (.) will be encoded to "%3A". But the macro would leave "%3A" unchanged because it's already encoded.

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 Insert cachebuster macro so that it replaces the placeholder:

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

When you traffic DFA impression tracker in DFP, select the standard ad tag and insert CACHEBUSTER macro to reduce the discrepancies.

Example tag: http://ad.doubleclick.net/ad/Nxxxx.site-keyname/Byyyyyyy;sz=1x1;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 confirmation letting you know. (If the third-party creative redirects to a Flash file, the confirmation won't be displayed, even if your creative is tracking clicks correctly.)
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:

  • Simplified URL 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 Escaping

%%DESCRIPTION_URL_UNESC%%

Unescaped

%%DESCRIPTION_URL_ESC_ESC%%

Double-escaped

Use %%DESCRIPTION_URL_ESC_ESC%% (double-escaped) when the macro is inside a URL, and use %%DESCRIPTION_URL_UNESC%% (unescaped) in other contexts.

In redirect ad tags, these macros expand 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.

DFP also supports %%DESCRIPTION_URL%%, which does the same thing as %%DESCRIPTION_URL_UNESC%%, so there's no need to recode older creatives and templates.
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 Escaping

%%REFERRER_URL_UNESC%%

Unescaped

%%REFERRER_URL_ESC_ESC%%

Double-escaped

Use %%REFERRER_URL_ESC_ESC%% (double-escaped) when the macro is inside a URL, and use %%REFERRER_URL_UNESC%% (unescaped) in other contexts.

This macro expands to the referrer URL (the URL of the page where the video player is located) in redirect ad tags. It does so in the following manner: DFP parses the ad tag's URL query parameter, isolates the referrer URL, and replaces the macro text with that URL. 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.
DFP also supports %%REFERRER_URL%%, which does the same thing as %%REFERRER_URL_UNESC%%, so there's no need to recode older creatives and templates.
Video title macro
Macro Description and requirements

%%VIDEO_TITLE%%

  • Expands to the title of the video.
  • Single-escaped.
  • Content ingestion is required for this macro to work.