Newsletter ads can be used to display Google Ad Manager reservation and Programmatic Guaranteed ads in email newsletters. This guide describes how to implement newsletter ads in your email newsletters.
Overview
Here's the high level workflow for implementing a newsletter ad:
- Create or select an Ad Manager ad unit.
- Create or select an Ad Manager line item.
Remember the following guidelines:
- Expected creatives must contain all of the sizes of the ad creatives you expect to appear in newsletters.
- Targeting must include the ad unit from step 1.
- Only image creatives are supported for newsletter ads.
- (Recommended) Configure a house line item to serve as a backup, in the event an ad doesn't fill.
- Craft a newsletter ad tag.
- Insert the newsletter tag at the spot where you want the ad to appear in your newsletter.
Newsletter ad tag format
A newsletter ad tag consists of an HTML image (img) element, nested inside of
an HTML anchor (a) element. Each newsletter ad tag must be followed by an
"About this ad" link, to provide information to users
about the ad displayed.
<!-- Newsletter ad tag -->
<a href="JUMP_URL?AD_PARAMETERS" target="_blank">
<img src="AD_URL?AD_PARAMETERS">
</a>
<!-- "About this ad" link -->
<a href="JUMP_URL?AD_PARAMETERS&click_type=wta">About this ad</a>
The formats of the anchor href and image src URLs are as follows:
| JUMP_URL | https://securepubads.g.doubleclick.net/gampad/jump |
| AD_URL | https://securepubads.g.doubleclick.net/gampad/ad |
| AD_PARAMETERS |
ptt=21&iu=AD_UNIT_PATH&sz=CREATIVE_SIZES&clkk=CLKK_VALUE&clkp=CLKP_VALUE&url=URL&t=TARGETING_KEY_VALUES
|
See the example section for a complete newsletter ad tag example using mock values.
Here is a detailed explanation of the supported newsletter ad parameters:
| Parameters | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
ptt |
Must always be set to
|
||||||||||
iu |
An ad unit path, which identifies the Ad Manager ad unit to display. Ad unit paths must have the following format:
|
||||||||||
sz |
The sizes of the ad creatives eligible to appear in this ad slot. Make sure the sizes listed here match the sizes selected in the Expected creatives field of your selected line item. Multiple sizes may be specified, separated by a pipe (
|
||||||||||
clkk |
A string that is unique per recipient, per email campaign. Every newsletter ad included in your email must specify a unique
To generate the The
To generate a
|
||||||||||
clkp |
A string that uniquely identifies a single newsletter ad placement. This parameter is required when multiple newsletter ads are included in an email. If your newsletter contains only a single ad placement, this parameter may be omitted.
|
||||||||||
url |
The “view in browser” URL for the current newsletter. The
|
||||||||||
t |
Targeting key-values. Keys and values are separated by an equals ( Existing restrictions for key-values apply to newsletter ads. See Get started with key-values for details.
|
||||||||||
Example
Here's an example of what a complete newsletter ad tag would look like for a set of mock values.
Ad unit path (iu) |
/1/example_ad_unit |
Creative sizes (sz) |
216x36|300x50|320x50 |
Unique string per email (clkk) |
*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|* |
Ad position (clkp) |
top |
Targeting (t) |
genre=comedy&movie=Lilo & Stitch |
View in browser URL (url) |
*|ARCHIVE|* |
<!-- Newsletter ad tag -->
<a
href="https://securepubads.g.doubleclick.net/gampad/jump?ptt=21&iu=/1/example_ad_unit&sz=216x36%7c300x50%7c320x50&clkk=*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*&clkp=top&url=*|ARCHIVE|*&t=genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch"
target="_blank">
<img
src="https://securepubads.g.doubleclick.net/gampad/ad?ptt=21&iu=/1/example_ad_unit&sz=216x36%7c300x50%7c320x50&clkk=*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*&clkp=top&url=*|ARCHIVE|*&t=genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch">
</a>
<!-- "About this ad" link -->
<a
href="https://securepubads.g.doubleclick.net/gampad/jump?ptt=21&iu=/1/example_ad_unit&sz=216x36%7c300x50%7c320x50&clkk=*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*&clkp=top&url=*|ARCHIVE|*&t=genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch&click_type=wta">
About this ad
</a>
Frequently asked questions
How do I generate a valid clkk value?
Refer to the clkk parameter reference.
What combination of merge tag variables should I use to form the clkk value?
Since available merge tag variables and appropriate syntax vary depending on
your Email Service Provider (ESP), we can't advise on or verify your clkk
values. We recommend that you refer to your ESP's documentation to identify a
combination of variables that will give you an string which is unique per user
and per email campaign.
Here's the documentation for some commonly used ESPs:
How do I know if my clkk value is correct?
When your clkk value is correct, it generates a string that's unique per user
and per email campaign. To verify this, you should generate test emails, click
the ads contained within them, ensure you're directed to the correct destination
URL, and that clicks are being reported in Google Ad Manager.
If you haven't already, we strongly recommend that you review the
newsletter ad tag reference to learn more about generating
correct clkk values. Here are some important requirements:
- The combination of "merge tags" that make up a
clkkvalue must be unique per user and per email campaign. If yourclkkvalue contains only one variable (for example,clkk=%UMF_MD5), it is most likely not unique enough. - An individual ad placement must specify the same
clkkvalue in both its anchorhrefand imagesrcURLs. If thehrefandsrcfor a given newsletter ad don't have the sameclkkvalue, the ad won't serve properly and may have unexpected behaviors.
Why are ads not appearing in my newsletters?
Here are some common issues that might cause newsletter ad insertion to fail:
- The newsletter ad tag is incorrect.
- The HTML anchor
hrefand imagesrcparameters don't match. - The ad URL does not include the
ptt=21parameter. - The tag contains empty spaces.
- There are typos or parameters not concatenated with an ampersand (
&). - Merge tags introduce invalid characters when rendered by your ESP.
- Contains PII such as email address or credit card number.
- The HTML anchor
- The ad unit path is incorrect.
- The line item is not active.
Why are users landing on an incorrect page after clicking an ad?
This is likely due to a clkk value that isn't unique. Refer to the
clkk parameter reference for details.
Why are clicks not being reported in Ad Manager reporting?
Here are two possible reasons:
- Your ESP's click tracking feature has been turned on, impacting Google's ability to record clicks.
- Your
clkkvalue is incorrect. Refer to theclkkparameter reference for details.
How do I know if my ESP's click tracking feature is turned on?
Refer to your ESP's documentation or reach out to their customer support for more information.
How can I show different creative sizes depending on the type of device or screen size?
You can use CSS @media queries to dynamically size creatives
based on browser viewport size. In the following example, when the viewport
width is at most 480px, the ad img element (identified by class="ad")
occupies 100% of its parent container width; when the viewport width is at least
480px, it occupies only 50% of its parent container width. The aspect ratio of
the ad remains the same in both cases, as long as no other size is specified for
the HTML img element.
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<style>
@media only screen and (max-width: 480px) {
.ad {
width: 100%;
}
}
@media only screen and (min-width: 480px) {
.ad {
width: 50%;
}
}
</style>
</head>
<body></body>
</html>