Build and Upload an AppLovin Playable Ad

AppLovin accepts one self-contained HTML file.

Generated output

Needle creates dist/AppLovin/index.html. The file includes MRAID 2.0 support and all game resources.

Requirements

An AppLovin advertiser account
An advertised app
Access to Media → HTMLs

Read the current AppLovin HTML playable specifications.

1. Add the profile

playableAds: {
    name: "MyGame",
    appStoreUrls: {
        ios: "https://apps.apple.com/app/id0000000000",
        android: "https://play.google.com/store/apps/details?id=com.example.game",
    },
    platforms: [{
        platform: "applovin",
        maxBytes: 5_000_000,
        reportPath: "artifacts/applovin-playable-build-report.json",
    }],
}

See Build Playable Ads for the complete Vite configuration.

2. Build the file

npm run build -- --production

Do not put dist/AppLovin/index.html in a ZIP file.

The profile checks these rules:

Maximum file size: 5 MB
Resource encoding: Base64 or Base122
External game requests: none
Audio and timer start: after the first interaction
Lifecycle and CTA API: MRAID 2.0
WebGL fallback: present

Read artifacts/applovin-playable-build-report.json for the file size, hash, and URL results.

3. Test the file

Open AppLovin Playable Preview.
Upload dist/AppLovin/index.html.
Start and complete the game.
Press the CTA.
Test portrait and landscape.
Reload the preview.
Test the first interaction again.

4. Upload the file

Open AppLovin Ads Manager.
Open Media → HTMLs.
Select Upload.
Select dist/AppLovin/index.html.
Select the app and campaign.
Preview the ad.

Upload control

If Upload is not visible, ask the account owner to check your permissions.

Test on a device

Install AppLovin Playable Preview for iOS or Android.

Test touch, audio, pause, resume, orientation, and the CTA.

Test with an agent

agent-browser --session applovin open "https://p.applov.in/playablePreview?create=1"
agent-browser --session applovin snapshot -i -C
agent-browser --session applovin upload @eN /absolute/path/to/dist/AppLovin/index.html
agent-browser --session applovin wait 3000
agent-browser --session applovin errors

Use the upload element from the latest snapshot. Inspect the playable frame for game requests.

Troubleshooting

Error	Action
External request	Rebuild the AppLovin profile. Remove remote fonts, media, workers, analytics, and configuration.
CTA does not open	Add a store URL. Call `NeedlePlayableAd.open()` from the install button.
First tap opens the store	Start the game on the first tap. Use a separate tap for the CTA.