Playable ad blank screen in Unity Ads: 1 cause, 7 checks

Unity’s docs name one cause of a playable that works locally but shows a blank screen in the ad unit: the file still references an asset by path or URL. The other seven items below are not named as blank-screen causes on any page we read. They are checks taken from Unity’s playable specification, best practices and moderation pages, each of which can break playback or get a pack rejected. Go through all eight, and finish on a real device.

What Unity’s docs say about a blank screen

Unity’s playable specifications page has one sentence on the subject: a playable that works locally but shows a blank screen in the ad unit “usually still references an asset by path or URL”. The page also gives the reason. The device downloads only the HTML file from the content delivery network (CDN), and Unity Ads ignores anything outside that file.

Unity’s playable best practices page has no blank-screen section and lists no causes. So this article mixes one documented cause with seven checks. We picked those seven because Unity’s pages say each one can break a playable. Whether a given one produces a blank screen, rather than a crash, a rejection or a broken layout, the docs don’t say.

#	Check	Where it comes from	Named by Unity as a blank-screen cause
1	Asset referenced by path or URL	Specifications	Yes (“usually”)
2	Network requests (XHR)	Specifications, moderation checks	No
3	MRAID ready and viewability	Specifications, best practices	No
4	Polyfills, Android 5 and iOS 13	Specifications, moderation checks	No
5	Console errors	Moderation checks	No
6	Orientation changes	Specifications, rejected page	No
7	Minification and file size	Specifications, moderation checks	No
8	Testing only in a desktop browser	Best practices	No

1. Find assets still referenced by path or URL

This is the documented cause. Unity’s spec asks for a single HTML file named index.html, with every image, audio and video asset inlined as base64 data and no references to other files, folders or assets through relative paths or remote URLs.

How to check:

1. Search the final built file for references. This command prints the start of every src and href value, every url(...) and every absolute URL:

grep -noE "(src|href)=\"[^\"]{0,40}|url\([^)]{0,40}|https?://[^\"' )]{0,50}" index.html

2. Read the matches. Every src, href and url(...) should start with data: (or #). Some http:// matches are harmless, such as the XML namespace in inline SVG, but each one deserves a look.
3. Copy only index.html into an empty folder and open it. A relative path that worked next to your project folder now fails the same way it fails in the ad unit.

Look for fonts loaded from CSS, a favicon link, a <script src> tag and images set from JavaScript by file name.

2. Remove network requests

Unity’s spec says the playable runs without network requests (XHR) and can’t load images, configuration or other content from a server at runtime. The moderation checks repeat it: no XHR other than permitted analytics calls. The spec adds that Unity handles start, view and click attribution on the server side, so the playable does not fire its own attribution events.

How to check: open the browser’s Network tab, reload, play to the end card, and expect one request, the document itself. Any fetch, XHR, font, script or tracking call is a defect. The pages we read say Unity can permit analytics calls without personal data, but not how a call gets permitted. Don’t add your own.

3. Start only after the MRAID ready event

The spec requires MRAID 3.0. The Unity Ads webview injects MRAID, so the playable needs no MRAID script tag. Start the playable only after the ready event and only when the ad is viewable, pause it when it isn’t, and don’t start on page load.

How to check: confirm the order in your code: ready, then isViewable(), then start, then viewableChange for pause and resume. Look for a <script src="mraid.js"> in the output and remove it. That is our reading: a script tag pointing at a separate file is the same kind of outside reference as in check 1. If your own test page never sends ready, the playable sits idle, which looks broken. Unity’s pages don’t tie this to a blank screen. The full pattern is in our MRAID 3 playable skeleton.

4. Check polyfills and older Android and iOS versions

Unity lists Android 5 or later and iOS 13 or later. The moderation checks say the content must not contain polyfill issues for older Android versions.

How to check: look at the compile target in your bundler (in Vite it is build.target) and run the final build on the oldest Android and iOS devices you have. A general point, not a Unity claim: if the webview can’t parse your script or lacks an API you call without a fallback, the script stops and nothing draws. The pages don’t say which webview versions Unity Ads uses, or what a polyfill issue looks like in moderation.

5. Open the console and fix every error

The moderation checks list “doesn’t include console log errors”. How to check: open the final file in a desktop browser with the console open, load it, play it through, and reach the end card. A failed asset request also shows up there as an error, so this check catches leftovers from checks 1 and 2. On a device, a remote inspector helps if your test route allows one. The docs we read don’t say whether the ad unit’s webview can be inspected.

6. Rotate the device while it plays

The spec asks for portrait and landscape from a single responsive build that adjusts on resize and orientation change. Unity’s rejected page lists, as a common reason, an ad that doesn’t function properly when switching between portrait and landscape.

How to check: rotate a real device mid-play, and on desktop drag the window from tall to wide while it runs. A common trap in canvas games (general experience, not a Unity statement) is reading the size once at load. Also keep text and buttons away from the top and bottom areas where Unity draws its own controls. The page says those areas can change over time.

7. Check minification and file size

Unity’s spec asks for a file under 5 MB with whitespace removed and names shortened. The moderation checks list both items: code correctly minified, not expanded, and size under 5 MB. The best practices page adds that the playable should reach its first interaction in under 2 seconds on a mid-tier device.

How to check: run wc -c index.html and open the file; minified code is a few very long lines. Base64 makes assets about a third larger, so roughly 3.75 MB of raw assets already uses up 5 MB (arithmetic, not a Unity statement). The docs don’t say what the ad unit does with an oversized file, or how load time is measured.

8. Test on a real device, not only in a desktop browser

Unity’s best practices page says a desktop browser or simulator doesn’t run your playable in the real ad unit, and many common rejection reasons only appear on a real device. Use the Ad Testing app: the User Acquisition dashboard generates a QR code for each creative pack when you select Show QR code. Also make sure the final build runs without MRAID, so you can test the complete playable in a desktop browser first. The build recipe is in from an HTML5 game to a single-file playable.

DarkCore Ramet has a Playable Builder and sends a video uploaded once to every app that needs it (creatives). Neither replaces the device test.

What the docs don’t say

• No page we read has a list of blank-screen causes. The only link between a blank screen and a cause is the one sentence in check 1.
• How moderation tests a playable is not described.
• The webview versions that inject MRAID are not listed.
• How the Ad Testing app works beyond the QR code step is not described.