HTML5 ZIP Google Ads: Structure, Assets and Size
Most HTML5 upload failures come from the archive, not the creative. Here is how to structure the ZIP, handle assets and paths, and test it before Google Ads sees it.
Key takeaways - Put index.html at the root of the ZIP. Zip the contents of your build folder, not the folder itself. - Make the package fully self-contained: every script, font, image and sound lives inside the archive and is referenced by a relative path. - Keep the file list short and boring: one entry HTML file, a few asset folders, no leftover system or tool files. - Check the current size and file-type limits in Google's documentation before you export, then stay comfortably under them. - Unzip into a fresh folder and test offline before uploading. Most packaging problems show up immediately.
Why packaging fails more often than creative
When an HTML5 ad is rejected, people tend to look at the design first. In practice the creative is often fine and the archive is the problem. The ad works from your project folder, but the ZIP has a different layout, a missing file, or a path that only resolved on your machine.
Google Ads does not run your build tools. It receives an archive, unpacks it, looks for an entry point and tries to render it in a controlled environment. Anything that depends on your local setup breaks there. Treat the ZIP as a small, sealed website that has to work with no help from the outside.
If you want the upload steps inside the Google Ads interface, see How to upload an HTML5 ZIP to Google Ads (without failing policy). This article is about what goes inside the archive.
The correct HTML5 ad ZIP structure
A clean package looks like this when you open it:
index.htmlcss/with your stylesheet, if it is not inlinedjs/with your scriptsimg/with images and sprite sheetsaudio/with sounds, if the ad uses anyfonts/with font files, if you use custom type
The important part is what is not there: no wrapping folder, no source files, no notes, no unused experiments. A flat, predictable layout is easier for a validator to read and easier for you to debug.
index.html at the root
The entry file must sit at the top level of the archive. The most common mistake is right-clicking a folder named my-playable and choosing "compress". Many operating systems then produce a ZIP whose only visible item is my-playable/, with index.html one level down. Depending on the validator, that can cause an outright error, a blank preview, or a message saying no HTML file was found.
The fix is simple. Open the build folder, select everything inside it, and compress that selection. Then open the resulting ZIP and confirm that index.html is visible immediately, with no folder to click through first.
One entry file
Use one HTML file as the entry point. If your build tool produces several pages, or you have leftovers such as index-old.html, remove them. Multiple HTML files make it unclear which one is the ad, and they invite validation noise.
Remove system and tool leftovers
Archiving tools and build setups often add files you never wanted:
- macOS folders such as
__MACOSXand.DS_Storefiles - Windows
Thumbs.db - source maps,
node_modules, config files and.gitfolders - readme or license text files copied along by accident
None of this helps the ad. At best it wastes bytes; at worst it is a file type the validator does not accept. Clean the folder before zipping, or use a zip command that excludes these entries.
Paths and references
Every reference inside the ad should be a relative path that resolves inside the archive.
- Use
img/hero.png, not/img/hero.pngand not a drive path from your own machine. - Match capitalization exactly. A file named
Hero.PNGreferenced ashero.pngmay work on one operating system and fail on another, because some file systems ignore case and others do not. - Avoid spaces and unusual characters in file names. Lowercase letters, digits, hyphens and underscores are safe.
- Do not depend on query strings or cache-busting parameters on local files.
A good test is to copy the unzipped folder somewhere else, such as your desktop, and open index.html from there. If anything is missing, a path is wrong.
Keep everything inside the package
The ad should make no external requests for its own assets. In practice that means:
- no scripts loaded from a public CDN
- no web fonts pulled from a font service
- no images hosted on your own website
- no analytics or tracking libraries fetched remotely
This is partly policy and partly practicality. The ad runs in a controlled environment, and calls to unknown hosts are a common reason for rejection or a blank render. It also removes a failure mode: if the remote file is slow or unavailable, the ad is broken for that impression.
If your code uses a library, bundle it into your own script file. If you use a custom font, include the font file and reference it locally, or use a system font stack if the design allows it.
Assets: what to include and how to keep them light
Google publishes the accepted file types and the maximum package size for HTML5 ads, and both have been revised over time. Check the current requirements in the Google Ads display ad specs before you finalize the export, rather than trusting a number from memory or an older blog post. Specs can also differ by campaign type, so confirm the one that matches where the ad will run.
Whatever the exact limit is, a lighter package is better. It loads sooner on mobile connections, and a playable that loads slowly loses people before the first interaction.
Practical ways to reduce weight:
- Resize images to the size they are displayed at. A background drawn far larger than any screen it will fill is pure waste.
- Use sprite sheets for repeated game elements, so you ship one image instead of many small ones.
- Prefer vector shapes or CSS for simple UI such as buttons, badges and progress bars.
- Compress audio and keep it short. Use only the sounds that reinforce the interaction.
- Subset fonts to the characters you actually need, or drop custom fonts entirely.
- Minify CSS and JavaScript and remove code the ad never calls.
- Drop anything the player never reaches, such as extra levels, unused animation frames or a second language you are not serving.
Do this work before the final zip. Compressing the ZIP itself helps little with files that are already compressed, such as most PNG, JPEG and audio files, so the savings have to come from the assets.
Interaction and exit behavior
A playable needs a defined way to send the user to the store, and Google Ads expects that to be implemented in the way the campaign type requires. Display ads traditionally use a click-through variable, while App campaigns use a different exit mechanism. The details are covered in the clickTag for Display HTML5 checklist and the ExitApi article for App campaigns. The packaging point is simple: any required script reference or exit call must be present and must not point outside the archive.
Test the package before you upload
Run the same routine every time. It takes a few minutes and catches most problems.
- Create the ZIP from the contents of the build folder. Do not zip the parent folder.
- Open the ZIP and look at the top level. You should see
index.htmland your asset folders, nothing else. - Extract it into a brand-new folder. Never test from the project directory, where files may resolve by accident.
- Disconnect from the network and open
index.html. Anything that fails now was relying on a remote file. - Check the browser console for missing-file errors and blocked requests.
- Test on a real phone, in portrait and landscape if the ad supports both. Touch handling and audio behave differently from a desktop browser.
- Compare the file size against the current spec from the official page, with room to spare.
If the upload still fails, the rejection message usually points to a specific cause. HTML5 Ad Disapproved in Google Ads: Causes and Fixes walks through the common ones, and Playable HTML5 QA checklist covers the broader review.
A simple naming and versioning habit
Keep one build folder per version and name the ZIP after it, for example puzzle-hero-v3.zip. Do not overwrite earlier archives. When a network rejects an upload or performance changes, you want to know exactly which package was live. Keep the source project separate from the build output so that the folder you zip contains only what the ad needs.
Common mistakes at a glance
- Zipping the parent folder, which buries
index.html. - Leaving
__MACOSX,.DS_Storeor source maps in the archive. - Referencing a file with the wrong capitalization.
- Loading a library or font from a remote host.
- Shipping full-resolution art that is never displayed at that size.
- Uploading without ever opening the ZIP once.
Where a generator fits
If you build the ad by hand, the checklist above is your quality gate. If you use a tool to generate the playable, the same checks still apply, because the archive is what gets reviewed. PlayableRun exports a ZIP intended for Google Ads, but you should still open it, extract it and test it as described here. The routine takes minutes and is worth keeping regardless of how the package was made.
To see what a finished package behaves like before you build your own, try the live examples at /demos, or create a free account and run your own export through the test routine above.
Frequently asked questions
›Where should index.html go inside the ZIP?
At the top level of the archive. When you open the ZIP, index.html should be visible immediately, not inside a wrapping folder. Zip the contents of your build folder, not the folder itself.
›Can my HTML5 ad load files from a CDN or my own server?
It should not. Keep scripts, fonts, images and audio inside the ZIP and reference them with relative paths. Remote requests are a common cause of rejection or blank previews.
›What is the maximum file size for an HTML5 ad ZIP?
It depends on the format and has changed over time, so check the current Google Ads specification before exporting. Whatever the limit, a lighter package loads sooner on mobile connections.
›Why does my ZIP work locally but fail on upload?
Usually a path or layout problem: a wrapping folder, a capitalization mismatch in a file name, an absolute path, or a dependency on a remote file. Unzipping the archive into a new folder and opening it offline exposes most of these.
›Should I include more than one HTML file?
No. Use one entry file named index.html and remove leftover test pages. Multiple HTML files make it unclear which one is the ad.
Turn your store listing into a playable
Paste an App Store or Google Play link and get an HTML5 playable you can test in minutes. The first one is free.
Keep reading
- Google Ads HTML5
HTML5 Display Ads vs App Campaigns: Different Code
7 min read
- Google Ads HTML5
Google Ads HTML5 Eligibility: Get Your Account Ready
7 min read
- Google Ads HTML5
Self Contained HTML5 Ad: No CDNs, No Web Fonts
8 min read