Build and Upload a Meta Playable Ad

A Meta playable ad contains a lead-in video, a full-screen game, and an app-install CTA.

Generated output

Needle creates dist/Meta/playable.zip. The ZIP contains one self-contained index.html file.

Requirements

A Meta Business Portfolio
An ad account
A registered mobile app
A lead-in video

Read the current Meta playable specifications. Then read the Meta upload procedure.

1. Add the profile

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

See Build Playable Ads for the complete Vite configuration.

2. Build the ZIP file

npm run build -- --production

The ZIP has this structure:

playable.zip
└── index.html

Meta applies these rules:

Maximum ZIP size: 5 MB
HTML location: ZIP root
MRAID: not required
JavaScript redirects: not permitted
XMLHttpRequest: not permitted
External game resources: not permitted
CTA API: FbPlayableAd.onCTAClick()

3. Test the ZIP file

Open Meta Playable Preview.
Upload dist/Meta/playable.zip.
Start and complete the game.
Press the install CTA.
Check the package and CSP results.
Check the file-load results.
Check the CTA result.

The CTA result becomes green after the call to FbPlayableAd.onCTAClick().

4. Create the ad

Open Meta Ads Manager.
Select + Create.
Select App promotion.
Select the registered app at ad-set level.
Select Single image or video at ad level.
Select Playable source under Destination.
Select Set up playable ad.
Select Upload playable asset.
Upload dist/Meta/playable.zip.
Preview the playable.
Select Done.
Add the lead-in video.

Placements

Meta supports selected Facebook, Instagram, and Audience Network placements. Ads Manager lists the enabled placements for the campaign.

Test with an agent

Use Meta Playable Preview without a campaign. Upload the ZIP and record all console, CSP, file-load, and CTA results.

The upload control opens a file chooser. Handle the file chooser after you select Upload playable asset.

Select Refresh playable before a second test.

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

Test on a device

Use the device or placement preview in Ads Manager. Test portrait layout, touch, audio, hide, resume, performance, and CTA access.

Troubleshooting

Error	Action
Upload control is absent	Check the objective, registered app, permissions, and placements.
ZIP rejected	Check the 5 MB limit. Check that `index.html` is at the ZIP root.
CSP blocks a data URL	Rebuild the Meta profile. The profile uses Blob URLs for embedded game files.
Redirect rejected	Call `NeedlePlayableAd.open()`. Do not use `window.open()` or `location`.
CTA does not work locally	Use Meta Playable Preview. The preview supplies `FbPlayableAd`.

Different Meta product

Facebook Instant Games use FBInstant. They require a different build and upload procedure.