Playable не працює в Unity Ads: порожній екран

Коли playable не працює в Unity Ads і показує порожній екран, хоча локально все запускається, першим ділом перевірте index.html на посилання на асети за шляхом чи URL. Лише цю причину Unity називає в документації прямо. Решта сім пунктів нижче — перевірки зі специфікації та модерації, а не «причини від Unity»: вони ламають відтворення або ведуть до реджекту, але який із них дає саме порожній екран, доки не кажуть.

Вісім перевірок в одній таблиці

№	Що перевірити	Звідки пункт
1	Посилання на асети за шляхом чи URL	Unity називає причиною прямо
2	Мережеві запити (XHR)	специфікація, модерація
3	MRAID ready і видимість реклами	специфікація
4	Старі Android, iOS 13, polyfill	специфікація, модерація
5	Помилки в консолі	модерація
6	Поворот екрана	специфікація, список причин реджекту
7	Мінімізація й розмір файлу	специфікація, модерація
8	Тест лише в десктопному браузері	best practices

1. Посилання на асет за шляхом чи URL

Це єдиний пункт, де Unity пише про порожній екран. На сторінці специфікації playable сказано: playable, який працює локально, але показує порожній екран у рекламному юніті, зазвичай досі посилається на якийсь асет за шляхом чи URL. Вимоги до файлу там само: один index.html, менше 5 МБ, усі картинки, аудіо й відео всередині у вигляді base64, жодних посилань на інші файли, теки й віддалені адреси. Пристрій завантажує з CDN лише HTML-файл, усе інше Unity Ads ігнорує.

Локально цього не видно: поруч лежить тека з картинками, і браузер знаходить ./img/hero.png. У рекламному юніті тієї теки немає.

Як перевірити. Проженіть фінальний файл через grep: він покаже все, що схоже на посилання й не починається з data:.

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

Розберіть кожен рядок виводу. Адреса виду http://www.w3.org/2000/svg — це ідентифікатор простору імен в SVG, а не запит. Рядки всередині самої бібліотеки (рушія, аналітики) теж бувають просто текстом. А от src="img/hero.png" чи url(./font.woff2) — це саме той випадок, про який пише Unity.

Команда не ловить шляхи, що збираються в JavaScript: this.load.image("hero", "assets/hero.png"), new Audio("snd/tap.mp3"), fetch("config.json"). Їх шукайте окремо за load., Audio(, fetch(, XMLHttpRequest. Як зібрати проєкт, щоб усі асети опинилися всередині файлу, розібрано в статті з HTML5 гри у playable одним index.html.

Решта сім перевірок: що це за пункти

На сторінці best practices для playable немає розділу про діагностику порожнього екрана й переліку причин. Далі йдуть вимоги специфікації та список перевірок модерації. Порушення будь-якого з них може зламати playable або привести до реджекту, але звʼязок «пункт — порожній екран» тут наше прочитання, а не твердження Unity.

2. Мережеві запити

Згідно зі специфікацією, playable працює без мережевих запитів (XHR) і не може підтягувати із сервера картинки, конфіг чи інший контент під час показу. Unity може дозволити аналітичні виклики, які збирають дані про дії гравця, але без персональних даних. Свою атрибуцію (старт, перегляд, клік) playable не шле: це Unity рахує на своєму боці. У перевірках модерації те саме правило: жодних XHR, крім дозволених аналітичних викликів.

Як перевірити: відкрийте файл у браузері з DevTools на вкладці Network, перезавантажте сторінку й подивіться, що крім самого документа нічого не запитувалося. Потім увімкніть режим Offline і перезавантажте ще раз. Якщо в офлайні playable поводиться інакше, щось підтягувалося по мережі: шрифт за URL, JSON з налаштуваннями, скрипт лічильника.

3. MRAID: чекайте на ready і видимість

Unity вимагає підтримку MRAID 3.0 і підтримує лише повноекранну рекламу MRAID 3.0. Webview Unity Ads сам підставляє MRAID, тому тег зі скриптом mraid у playable не потрібен. Запускати гру можна лише після події ready і лише коли реклама видима. Не стартуйте на завантаженні сторінки: за словами Unity, усе, що крутиться до показу, зʼїдає перші секунди гравця й виглядає зламаним. Не підтримуються expand, resize, власні кнопки закриття, sms, tel, calendar, storePicture.

Чому це може дати порожній екран — наше припущення, доки про це мовчать: код чекає на подію, що не прийшла, або викликає mraid там, де його немає, і падає на першому рядку. Каркас зі специфікації (адаптовано з прикладу Unity):

// Чекаємо на готовність MRAID, потім налаштовуємо playable.
if (mraid.getState() === "loading") {
  mraid.addEventListener("ready", onReady);
} else {
  onReady();
}
function onReady() {
  mraid.addEventListener("viewableChange", onViewableChange);
  // Стартуємо, лише якщо реклама вже видима.
  if (mraid.isViewable()) startPlayable();
}
function onViewableChange(viewable) {
  if (viewable) startPlayable(); // запуск або продовження
  else pausePlayable(); // пауза і без звуку
}

startPlayable() і pausePlayable() у прикладі Unity не визначені, це ваш код. Розгорнутий каркас — у статті про MRAID 3 у playable. Як перевірити: додайте в onReady і onViewableChange виведення на екран у відладочній збірці (як window.onerror у перевірці 5) і переконайтеся на пристрої, що обидва спрацьовують.

4. Старі Android, iOS 13 і polyfill

Мінімальні версії за специфікацією: Android 5 та iOS 13. У списку модерації є окремий рядок: контент не повинен мати проблем із polyfill для старих версій Android. Які версії webview стоять на пристроях, Unity не пише, і що саме вважається «проблемою polyfill», теж.

Як перевірити: перегляньте цільовий рівень JavaScript у збирачі й пошукайте у фінальному коді свіжі методи, наприклад .at( чи structuredClone(, яких немає в старих webview. Якщо підключаєте polyfill, перевірте, що він сам не ламає старт. І запустіть на найстарішому пристрої, який у вас є.

5. Помилки в консолі

У перевірках модерації є пункт: у контенті не має бути помилок у консолі. Виняток, кинутий на старті, легко лишає екран порожнім.

Як перевірити: на десктопі відкрийте DevTools, перезавантажте сторінку й перегляньте консоль одразу після завантаження, після першого тапу та після повороту. Чи доступне налагодження webview в Ad Testing app, Unity не описує. Тому для відладочної збірки виведіть window.onerror прямо на екран, а з бойової це виведення приберіть.

6. Поворот екрана

Playable має працювати в портретній і альбомній орієнтації з однієї адаптивної збірки та підлаштовуватися під зміну розміру й орієнтації. На сторінці Rejected серед частих причин реджекту: реклама некоректно працює під час перемикання між портретом і альбомом. Окремі горизонтальний і вертикальний файли Unity позначає як такі, що застарівають, але вже завантажені продовжують працювати.

Як перевірити: поверніть пристрій не до запуску, а посеред гри. Потім ще раз поверніть назад. Дивіться, чи не зникла картинка, чи не скинувся стан і чи не зʼїхали кнопки під область, де Unity малює свої елементи.

7. Мінімізація й розмір

У перевірках модерації: код мінімізований, а не розкритий, файл менше 5 МБ. Специфікація розшифровує мінімізацію так: прибрано пробіли, імена скорочено. Best practices додають: playable має завантажитися й дійти до першої дії менш ніж за 2 секунди на пристрої середнього класу. Що вважається «середнім класом», як вимірюється завантаження і як рахується 5 МБ (десяткові чи двійкові), доки не кажуть, тож беріть запас.

Як перевірити: wc -c < index.html покаже розмір у байтах. Не забувайте, що base64 роздуває вкладені картинки приблизно на третину. Відкрийте файл у редакторі: якщо він читається як звичайний код з відступами, збірку треба мінімізувати.

8. Перевірка лише в десктопному браузері

Unity прямо попереджає: десктопний браузер чи симулятор не запускає ваш playable в справжньому рекламному юніті, і багато частих причин реджекту видно лише на реальному пристрої. Тому потрібні обидва кроки. Спершу фінальна збірка має запускатися й без MRAID, щоб повністю перевірити її в десктопному браузері. Потім потрібен реальний телефон: дашборд User Acquisition генерує QR-код для кожного паку креативів: оберіть Show QR code і відкрийте превʼю в застосунку Ad Testing.

На пристрої перевірте поворот під час гри, паузу й відновлення за viewableChange та те, що кнопка CTA відкриває потрібну сторінку в Google Play і App Store. Як влаштований застосунок Ad Testing поза межами QR-коду, Unity в цих матеріалах не пояснює.

Чого в доках не сказано

• Немає розділу з розбором порожнього екрана й списку його причин, крім посилання на асет.
• Невідомо, як модерація тестує playable.
• Не вказано, у яких версіях webview Unity Ads підставляє MRAID.
• Немає опису, чи можна дивитися консоль в Ad Testing app.

Якщо креативів багато, відео в DarkCore Ramet завантажується один раз і йде в усі потрібні апки. У DarkCore Ramet є Playable Builder.