contact_support Contact support
    • Maestro
    • Policies and specifications

    HTML5 package requirements

    Table of Contents

    Overview Package format Package structure Allowed file types Asset paths Click tracking (clickTag) Size meta tag Upload checks

    Overview

    This guide outlines the requirements for HTML5 creatives uploaded to Maestro. It is intended for users who create and package HTML5 creatives. Following these requirements helps ensure that packages pass upload validation, serve correctly, and track clicks as expected.

    For more information about how to upload the package in Maestro, see Manage creatives: upload HTML5 creatives.

    Package format

    Ensure that your package meets the following format requirements:

    • Deliver one ZIP file per creative.
    • The maximum file size is 29 MB (27.66 MiB).
    • One package is one creative and one size. To deliver several sizes, build one package per size.

    Package structure

    Ensure that your package adheres to the following structural requirements:

    • The package must contain exactly one index.html file.
    • Place index.html either at the root of the ZIP file or inside a single root folder.
    • macOS system files, such as __MACOSX folders and .DS_Store files, are ignored. You don't need to remove them.

    Allowed file types

    The package can contain web assets only, as described in the following table:

    Type Extensions
    Code and data html, htm, css, js, json, txt, xml
    Fonts ttf, otf, woff, woff2
    Images png, jpg, jpeg, gif, svg, webp
    Media mp4, webm, mp3

    Server-side scripts and executables (for example, PHP or EXE files) aren't allowed.

    Asset paths

    Ensure that your asset references comply with the following rules:

    • Reference every asset with a relative path, for example, images/logo.png.
    • We recommend including all files used by the creative in the package.

    Click tracking (clickTag)

    The creative requires a clickTag parameter for clicks to work. Maestro loads the creative with the click URL in a clickTag URL parameter. The creative must read this parameter and open the destination URL in a new window when clicked.

    When implementing click tracking, adhere to the following rules:

    • Use clickTag, clickTAG, or clicktag. Other spellings, such as ClickTag, aren't detected.
    • Don't hardcode the landing page URL in the creative. The landing page is set in the Click Url field in Maestro.

    The following example demonstrates how to read the parameter and handle clicks:

    var clickTag = new URLSearchParams(window.location.search).get('clickTag');
document.getElementById('ad').addEventListener('click', function () {
  window.open(clickTag, '_blank');
});

    Many packages declare the clickTag as a fixed value in the HTML head, for example, var clickTag = "https://www.example.com";. This method doesn't work in Maestro. The creative must read the clickTag from the URL parameter, as shown in the preceding code example.

    Maestro checks for a clickTag when you upload the package. If Maestro doesn't find a clickTag, it displays a warning but still lets you save. A creative saved without a working clickTag serves, but its clicks aren't tracked and don't reach the landing page.

     

    Size meta tag

    We recommend adding an ad.size meta tag to index.html so that Maestro fills in the creative's width and height automatically:

    <meta name="ad.size" content="width=728,height=90">

    If the tag is missing, enter the width and height manually when uploading.

    Upload checks

    Maestro checks the package on upload. Errors prevent you from saving, while warnings let you save. The following table describes the upload validation checks:

    This page describes errors and warnings that you might encounter when uploading an HTML5 package, along with solutions to resolve them.

    Message Type Description Resolution
    File type not allowed Error The entry <file name> has a file type that is not allowed. Remove any files whose file types are not on the allowed list.
    Invalid structure Error The archive contains two root folders (a, b). Place the bundle at the root or inside a single folder. Move all files to the root of the ZIP file or place them inside a single folder.
    More than one index.html Error The archive contains several entry points (index.htm, index.html). Keep only one index.html file. Keep only one index.html file at the package entry point.
    No clickTag Warning No clickTag was detected in this package. Clicks might not be tracked. Add the clickTag code as described in the Click tracking (clickTag) section.
    No index.html Error The archive contains no index.html or index.htm file at its root. Add an index.html file at the root of the ZIP file or inside a single root folder.
    Package could not be checked Warning Maestro could not check this package within 30 seconds. The package will be checked again when you save. Save the package. Maestro checks the package again on save.
    Package over 29 MB Error This HTML5 ZIP package is larger than the 29 MB maximum limit. Reduce the package size to 29 MB or less.

    RELATED ARTICLES