Skip to main content
An HTML5 creative is a ZIP of HTML, scripts and images. A seller’s ad server reads the ZIP when Apostra sends it, and it turns away a ZIP it cannot make clickable. That refusal arrives after you have saved the creative and moved on, so check these requirements before you upload.

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:
The declaration has to match this form:
  • It starts with var, then the name clickTag, 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 .html or .htm file. A declaration in a .js file is not found.
These forms are not detected. A ZIP that uses only them has no click tag, as far as the ad server is concerned: 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 in var 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.html contains % 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 file index.html does 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.
The creative’s seller entry then reads 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. V3 save_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 named index.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.
Both layouts are accepted, so a ZIP your design tool exported as a folder works without rebuilding it. What is refused is a ZIP with no 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.png to banner.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.
A design tool’s normal export meets all three. If yours does not, compress the folder again with your operating system’s built-in ZIP tool. Hidden files and folders, such as .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, the index.html described above:
Use the banner’s real pixel size. Apostra does not infer it from the file name, the CSS or the images. A creative with no size, or with a side larger than 10,000 pixels, is refused when you save it, and nothing is saved. Declare the size only in 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 the backup_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 CM360 https://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.
Saving a display tag is described in Bring data in.