Journey Of Online Media: Ad Tag

DoubleClick Macros – An Overview… Part 2

Continued from Part 1

File server macro

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 we can 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.

Notes:

%h will still work for creatives trafficked in DART, but we strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.
The syntax for a creative file's path using %h is: %h/advertiser_ID/filename.ext. For example, for advertiser 12345678 and creative file dclk1.gif, the syntax would be:%h/12345678/dclk1.gif
DART macros are case-sensitive. That is, %H is not a valid macro.

Geo ad server macro

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

Note:

Macros are case-sensitive. That is, %G is not a valid macro.
The expanded form of the geo ad server macro is not wrapped in quotes (single, or double). The macro can cause syntax errors with surrounding Javascript code if it's wrapped in quotes.

Height and width macros

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 we are 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.

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

Host name macro

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.

Note: DART macros are case-sensitive. That is, %A is not a valid macro.

Interstitial impression macro

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:

Notes: %i will still work for creatives trafficked in DART, but we strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.

Pattern match macro

We 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 we want to serve different creatives based on information we know about a user. For example, maybe we 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.

We are 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

In the custom or third-party creative, dynamically pass the criteria using the following macro:<some creative script here>...&gender=%%PATTERN:gender%%
The entire macro of %%PATTERN:gender%% will be replaced with "male".
DFP will call and serve the “male” creative file to this user.

Notes:

%p will still work for creatives trafficked in DART, but we strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.

%p is not supported with GPT tags. If you use GPT, you must use %%PATTERN:key%%.

DART macros are case-sensitive. That is, %P is not a valid macro.

Site name macro

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.

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:

Notes: %t will still work for creatives trafficked in DART, but we strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.

Source: Google Support

DoubleClick Macros – An Overview… Part 1

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 click through URLs. Ad server macros are useful for passing important information to your proprietary systems or third-party ad servers.

If the creative code is recognized as being from a certified vendor, then it will automatically insert the proper macros. If DFP don't recognize the third-party creative code, then we need to insert the macros manually. We 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 respective third-party to determine where to insert the macro.

For clients upgrading from DART for Publishers: Creatives that we trafficked in DART with DART macros will continue to serve as expected after we upgrade. However, it is strongly recommend that we use the new syntax, where available. This list represents all of the macros it supports in DoubleClick for Publishers for Creatives which traffic after upgrading.

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 we’re accurately counting impressions. Here is what the cache-busting macro looks like:

%%CACHEBUSTER%%

If we don't add the cache-busting macro to the creative code, we’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]

We 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%%

Notes:

%n will still work for creatives trafficked in DART, but we strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.
DART macros are case-sensitive. That is, %N is not a valid macro.

Click macro

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

Un-escaped click macro: %%CLICK_URL_UNESC%%
Double-escaped click macro: %%CLICK_URL_ESC_ESC%%

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

Notes:

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.
%c will still work for creatives trafficked in DART, but we strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.
Warning: 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.

Tips:

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.

Click-through URL macro

This macro can be helpful if we are traffic a custom creative and we 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 we 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%%).

Notes:

%u will still work for creatives trafficked in DART, but strongly recommend using the new syntax for all new creatives trafficked in the DFP upgrade.

Expand macro

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.

We can insert the %e macro at the end of the ad's click through 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 second-level ad unit ID serving the line item
%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 click through URL with any character that is safe for use in DFP click through URLs:

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

Could become: http://www.site.com/?1234567;4265598

Notes:

The %e macro cannot be used by DFA clients running click-commands on DFP sites. The advertiser_id or page_id values, for instance, will populate with the DFP values instead of the intended DFA values.