> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTML5 and display tag creative requirements

> What an HTML5 ZIP or a third-party display tag (CM360) needs so a Google Ad Manager seller accepts it: one click tag, a declared size, a backup image, and no unfilled CM360 placeholders.

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:

```html theme={null}
<script>
  var clickTag = "https://example.com";
</script>
<img src="banner.png" alt="" onclick="window.open(clickTag)" />
```

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:

| Form | Why it is not detected |
| - | - |
| `window.clickTag = "https://example.com";` | It is not a `var` declaration. |
| `var clickTag;` | It declares no value. |
| `var clickTAG = "…";` | The name is case-sensitive. |
| `var clickTag = new URLSearchParams(location.search).get("clickTag");` | The value is computed, not written in the declaration. |
| `var clickTag = "…";` in a `.js` file | Only HTML files are read. |

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:

| Macro | On the click |
| - | - |
| `{CACHEBUSTER}`, `{DOMAIN}`, `{GDPR}`, `{DEVICE_ID}` | Filled. |
| `{AXEM}` | Filled when the seller's Google Ad Manager network carries the `axem` key-value. |
| `{APP_BUNDLE}` | Not filled, because a display ad request carries no app bundle. |

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](https://docs.apostra.com/v3/landing-page-macros.md). 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](https://docs.apostra.com/v3/creative-sync-outcomes.md#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](https://docs.apostra.com/v3/html5-creative-requirements.md#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](https://docs.apostra.com/v3/manage-ads.md#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:

```html theme={null}
<meta name="ad.size" content="width=300,height=250" />
```

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](https://docs.apostra.com/v3/manage-ads.md#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](https://github.com/scope3data/embedded-sales-agent/pull/1251)
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:

| Placeholder in the tag | What happens |
| - | - |
| `[timestamp]` | Filled with GAM's `%%CACHEBUSTER%%`, so it is a fresh value on every request. |
| `[APIFRAMEWORKS]`, `[OMIDPARTNER]` | Passed through unchanged. They are optional in-app signals that only an app SDK can fill, and CM360 serves the ad without them. |
| Any other unfilled CM360 placeholder: `[gdpr]`, `[gdpr_consent_755]`, `[addtl_consent]`, `[gpp]`, `[gpp_sid]`, `[dc_rdid]`, `[dc_lat]`, `[tag_for_child_directed_treatment]`, `[tfua]`, `[ltd]`, `[dc_tdv]`, `[BREAKPOSITION]`, `[keyword]`, `[url_encoded_publisher_data]` | The creative is refused before it is uploaded to GAM, with the reason code `CM360_UNFILLED_PLACEHOLDER` naming the placeholders. GAM has no exact equivalent to fill them with. |

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](https://docs.apostra.com/v3/creative-sync-outcomes.md) 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](https://docs.apostra.com/v3/bring-data-in.md).

## Related

* [Creative sync outcomes](https://docs.apostra.com/v3/creative-sync-outcomes.md) shows where a creative
  stands on each seller, and why a seller did not accept it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.