Declare exactly one click tag
An ad server finds the creative’s exit, the place a click goes, from a plain JavaScript declaration in an HTML file in the ZIP. Google Ad Manager works this way, and so do most ad servers. Declare one click tag in the main HTML file,index.html (see “Package one entry point” below), and use it for the exit:
- It starts with
var, then the nameclickTag, optionally followed by digits (clickTag,clickTag1,clickTag2). The name is case-sensitive. - It assigns a quoted string on one line, in double or single quotes. An empty string is fine, because the approved click-through replaces the value.
- It is in an
.htmlor.htmfile. A declaration in a.jsfile is not found.
Declare one exit. A ZIP that declares two different click tags, for example
clickTag and clickTag1, has two exits, and one approved click-through cannot
fill both. Repeating the same clickTag declaration in more than one HTML file
is one exit.
The approved click-through replaces the declared value
The URL you wrote invar clickTag is not the final destination. When a
Google Ad Manager seller receives the ZIP, its sales agent writes the
click-through approved on the creative into the one click-tag declaration and
leaves every other part of the ZIP unchanged. Use any valid https:// URL while
you build the ZIP, and set the real destination on the creative.
An ad server accepts a click-through only when it is a valid URI, so characters
it would reject, such as spaces, braces and non-ASCII letters, are
percent-encoded when the value is written. The URL decodes to the same
destination.
Serve-time macros in the click-through
When Apostra’s click tracker is on, the click-through is that tracker, wrapping your landing page. Your creative’s identifiers are filled before it is sent. Serve-time macros, such as{CACHEBUSTER}, {DOMAIN} or a copy of a macro in
your landing page, are different: Google Ad Manager has to fill them when the ad
serves, and it fills no macro in a standard HTML5 creative’s click tag.
So when your landing page needs a macro that only Google Ad Manager can fill,
such as {DOMAIN} or {CACHEBUSTER}, the managed sales agent sends the ZIP to
Google Ad Manager as a custom creative instead. The ZIP’s files are uploaded with
it, its click tag becomes Google Ad Manager’s click macro, and the click-through
becomes the creative’s destination URL, where Google Ad Manager fills the macros.
Your landing page then receives the values, for example the site’s domain for
{DOMAIN}. Only your landing page decides this: the macros of Apostra’s own click
tracker never do.
Any other ZIP is sent as a standard HTML5 creative, and its click tag carries no
serve-time macro. The managed sales agent removes the click tracker’s own
serve-time parameters, such as its cache-buster and domain, so the click of a
standard HTML5 creative carries neither.
On the custom creative path, the managed sales agent’s HTML5 formats fill these
macros:
A creative whose landing page needs a macro Google Ad Manager cannot fill on the
click may be refused with
html5_click_macro_unfillable. Whole query values
containing unavailable {DOMAIN} or {APP_BUNDLE} follow the omission rules
below; other unavailable macros, including {PAGE_URL}, are refused.
The click of a Google Ad Manager HTML5 creative also does not carry your landing
page’s consent macro, {GDPR_CONSENT}, so a landing page that needs it is
refused with html5_click_macro_unfillable too. Use an image creative for a
landing page that depends on the consent string. {GDPR}, which says whether
GDPR applies, is filled.
A seller’s format lists the macros it fills; see
Landing-page macros. When a Google Ad Manager seller’s
HTML5 format lists none, Apostra sends the tracker with no serve-time macro in
it: no cache-buster, and no copies of macros in your landing page.
What a ZIP needs to be sent as a custom creative
The sales agent turns the ZIP’s root HTML file into one HTML snippet and uploads the other files with it, naming each by Google Ad Manager’s file reference. A ZIP that needs the custom creative path and cannot take it is refused before the buy is booked. It is never sent as a standard HTML5 creative instead, because your landing page would then receive the macros unfilled. The ZIP is refused when:- it has no single root HTML file:
index.html, or the only HTML file at the root; - it contains an SVG file. Use PNG, JPEG, GIF or WebP instead;
index.htmlcontains%followed by a letter anywhere except the click tag’s value, because Google Ad Manager would read that text as a macro;- a file that has to be uploaded on its own refers to another file in the ZIP.
A stylesheet or script that contains
%followed by a letter, or%%, is uploaded on its own, unchanged, for the same reason, and so is any fileindex.htmldoes not load directly. The paths inside such a file are not rewritten, so the files it names would not load; - the HTML is over about 500 KB, counting the stylesheets and scripts inlined into it.
failed, and the seller’s error carries
the code html5_bundle_not_custom_servable with recovery: "correctable" and
a message naming the file and the fix. Correct the ZIP and save it again; see
When the seller says the request must change.
A ZIP that does not declare exactly one var clickTag is refused with the code
html5_click_tag_invalid, also correctable, whichever way it would be sent; see
Declare exactly one click tag.
Write every reference to another file in the ZIP as a literal relative path in
the HTML, CSS or JavaScript, such as images/logo.png. A file that no literal
path refers to is not uploaded; the sales agent logs a warning and does not
refuse the ZIP. So a script that builds a file path while it runs, such as
"images/" + name, cannot load that file.
When Apostra warns you
To bring an HTML5 ZIP to a V3 advertiser, use the upload Task. Open the Creative library and choose Upload, or ask your assistant to upload the file. In Apostra chat you can also attach the ZIP to a message and ask the assistant to save it to an advertiser’s Creative library: it is saved the same way, with the same checks, without choosing the file again. Other assistants, such as Claude and ChatGPT, do not pass an attached file to Apostra, so there the assistant opens the upload Task and you choose the file. The upload Task takes a ZIP of up to 10 MiB (10,485,760 bytes). Apostra opens the ZIP’s HTML files, checks them against the requirements on this page, and saves the ZIP as a draft HTML5 creative. V3save_creative does not take ZIP bytes, so the
upload Task is the way to save one. To finish the draft, give it its click URL
and mark it complete in the Library, with no campaign needed; see
Finish an uploaded HTML5 ZIP or VAST draft.
If the check finds no click tag, or more than one different click tag, the ZIP
is still saved and the reply carries a warning. The warning names the problem, says what to
add, and links this page. It is a warning rather than a refusal because some
sellers use another click mechanism. A seller whose ad server needs a detectable
click tag, such as Google Ad Manager, still refuses the ZIP.
Fix it by adding the declaration above to the main HTML file and saving the
corrected ZIP to the creative. Apostra checks only a ZIP it receives in the
upload itself. It does not download a ZIP you linked by URL.
Package one entry point
The ZIP needs exactly one file namedindex.html. It is the entry point: the
file the ad server opens, and the place for the size and the click tag.
Put it in one of two places:
- at the root of the ZIP, alongside the rest of the creative; or
- inside a single folder that holds every other file in the creative.
index.html, one with
more than one, one nested more than a folder deep, or one whose enclosing folder
does not contain the whole creative. A creative that is refused is not saved.
__MACOSX entries and .DS_Store files that macOS adds when you compress a
folder are ignored, so they neither satisfy nor break this rule.
A file named something else, such as main.html or banner.html, is not an
entry point. Rename it to index.html.
Keep the ZIP plain
The seller unpacks the same ZIP you uploaded, so Apostra accepts only a ZIP that every unzipper reads the same way. A ZIP is refused, and nothing is saved, when:- a file or folder name uses anything other than letters A to Z, digits,
spaces, dots, dashes, underscores, parentheses and plus signs. Rename
bannér.pngtobanner.png, for example; - it is encrypted or password-protected, or compressed with a method other than the standard one;
- it contains a link (a symlink) or any entry that is not a plain file or folder.
.vscode or .cache, and the macOS entries
above are removed from the ZIP before it is saved. The seller receives only the
files Apostra checked. A hidden file must still be one of the file types an
HTML5 ZIP can carry (HTML, CSS, JavaScript, JSON, XML, images, fonts, MP3, MP4
and WebM), or the ZIP is refused.
Apostra checks how the ZIP is put together: its names, its entry point, its
size and its file types. It never runs the creative, and it does not judge what
the scripts do. A seller still reviews the creative under its own policies.
Declare the size
Every HTML5 creative needs a size, because a seller that lists one format per banner size matches the creative to a format by its size. Declare it in the entry point, theindex.html described above:
index.html. A ZIP in which another HTML file also
declares ad.size is refused, even when the two sizes match. For a ZIP the
declaration in index.html is required: formatParams does not replace it. The
ways to declare a size for a single HTML file or a display tag, including
formatParams, are in
Save an HTML creative with its size.
Add a backup image when the seller asks for one
Some sellers’ HTML5 formats require a backup image, the still picture shown where HTML5 cannot run. Where a seller’s format requires one, the creative needs an image asset in thebackup_image slot, and the format can also set a maximum
file size for it. A creative with no backup image, or one over the limit, does
not fit that format. Add the image to the creative and save it again.
Click URLs on Google Ad Manager display
The behavior below applies after the seller’s ESA deployment includes the display macro update and its trusted tracker hosts are configured. Until then, a creative with an unfillable token may be refused; check with the seller before relying on omission. When{DOMAIN} or {APP_BUNDLE} cannot be filled on a display request, the
seller’s agent removes a URL query parameter whose entire value is that token.
This also applies to landing-page parameters inside the Interchange click
tracker’s encoded rurl. Other bytes in the landing URL stay unchanged.
When an unfillable token is embedded in a larger value inside a configured
Interchange click tracker’s rurl, the tracker removes the token before
redirecting if its spelling matches the tracker. A token whose name contains
percent-encoded characters is refused because the tracker cannot recognize it. For a direct landing page or another tracker, the creative is
refused instead, so the landing page does not receive a literal token. Change
the URL to use a whole parameter value or remove the unfillable token and retry.
Malformed URL escapes and values that still contain encoded braces after decoding
are refused so that unresolved tokens do not reach the landing page.
Third-party display tags (CM360 tags) for Google Ad Manager sellers
A tag from Campaign Manager 360 (CM360) can carry bracket placeholders such as[timestamp] or [gdpr]. Google Ad Manager (GAM) expands only its own %%…%%
macros, so a CM360 placeholder reaches the page as written unless the seller’s
sales agent handles it first. For a GAM-backed seller the sales agent handles an
inline tag’s placeholders like this:
Fill or remove a refused placeholder in the tag, then save the corrected tag. The
refusal appears on the creative’s seller entry, as
Creative sync outcomes describes.
A GAM seller accepts a display tag in two forms, once the seller’s product
declares the delivery type in
supported_delivery_types:
inline_markup: the tag’s markup, sent unchanged as a third-party creative.paired_redirect: the tag’s ad-request URL with its click-through URL. When the ad-request URL is a CM360https://ad.doubleclick.net/ddm/ad/…URL, GAM runs it as an internal redirect, and CM360 handles clicks. Any other ad-request URL is sent as an image redirect with its click-through URL.
Related
- Creative sync outcomes shows where a creative stands on each seller, and why a seller did not accept it.