Build and Upload a Google Ads Playable

Google Ads calls this file an HTML5/Playable asset. App campaigns use a ZIP file.

Generated output

Needle creates dist/GoogleAds/playable.zip. The ZIP includes orientation data and the Google Exit API integration.

Requirements

A Google Ads account
A live iOS or Android app
An App campaign for installs
App conversion tracking
HTML5 upload access

1. Add the profile

playableAds: {
    name: "MyGame",
    platforms: [{
        platform: "google-ads",
        maxBytes: 5_000_000,
        reportPath: "artifacts/google-ads-playable-build-report.json",
        orientation: "portrait,landscape",
    }],
}

Set orientation to portrait, landscape, or portrait,landscape.

See Build Playable Ads for the complete Vite configuration.

2. Build the ZIP file

npm run build -- --production

Read the current Google App campaign specification.

Google applies these limits:

Maximum ZIP size: 5 MB
Maximum file count: 512
Layout: responsive
Game resources: local
Audio start: after interaction
Local storage: not permitted

Exit API

Needle includes Google's hosted exitapi.js. NeedlePlayableAd.open() calls ExitApi.exit().

Google reads the final store URL from the campaign.

3. Validate the ZIP file

Open the Google HTML5 Validator.
Select For App Campaigns.
Upload dist/GoogleAds/playable.zip.
Fix each applicable error.
Build the ZIP again.
Repeat the validation.

4. Add the ZIP to a campaign

Create or open an App campaign for installs.
Open the ad or asset editor.
Find the HTML asset.
Select + Add.
Upload dist/GoogleAds/playable.zip.
Test each configured orientation.
Add the required text, image, and video assets.
Save the campaign.
Submit the campaign for review.

In Google Ads Editor, select Manage → Ads → App ads for installs → HTML5 → + Add.

Test on a device

Use the campaign preview for the host test.

Use a temporary HTTPS address for an additional iOS and Android test. This test covers touch, layout, audio, and performance.

The browser test does not test the Google Ads host API.

Test with an agent

Use the public HTML5 Validator. Record its complete report.

The upload control opens a native file chooser in some browsers. Handle the file chooser before the test continues.

Use an authenticated account only for an authorized draft. Do not publish a campaign or change its spend without permission.

Troubleshooting

Error	Action
ZIP is too large	Reduce the size below 5 MB. Keep free space below the limit.
Orientation rejected	Set a supported `orientation` value. Build the ZIP again.
CTA is missing	Build the Google Ads profile. Call `NeedlePlayableAd.open()`.
External file rejected	Store game files in the ZIP. Keep only Google libraries that the specification permits.

Read Google HTML5 upload troubleshooting for more validator errors.