Прежде чем писать первую строчку кода, полезно понять, куда именно вы этот код отправляете. Яндекс Игры — не просто каталог ссылок: это среда со своими правилами хостинга, своим способом запуска игры, своей моделью денег и своей проверкой перед публикацией. Почти все типичные ошибки новичков — от неверного пути к SDK до звука, который продолжает играть поверх рекламы, — растут из непонимания этой механики. Эта глава даёт карту: дальше мы будем углубляться в каждую её область.
Всё, что описано ниже, сверено с официальной документацией yandex.ru/dev/games/doc/ru в сентябре 2026 года. Платформа развивается, поэтому спорные детали лучше перепроверять по первоисточнику — ссылки собраны в конце страницы.
Что такое платформа
Яндекс Игры — витрина браузерных HTML5-игр внутри экосистемы Яндекса. Игрок открывает страницу и играет: ничего не устанавливая, не регистрируясь отдельно, не скачивая клиент. Для разработчика это означает, что платформа берёт на себя три вещи, которые обычно приходится строить самому: хостинг, авторизацию и монетизацию. Ваша задача сводится к самой игре и к соблюдению правил площадки.
Каталог существует на нескольких страновых доменах (yandex.ru/games — российский, yandex.com/games — мультиязычный) и поддерживает десятки языков в формате ISO 639-1. Карточка игры показывается на языке того каталога, куда пришёл игрок, а если ваша игра этот язык не поддерживает — платформа подставляет запасной вариант. Отсюда практическое следствие, о котором мы поговорим отдельно: язык интерфейса игры нужно определять не по браузеру, а через SDK (ysdk.environment.i18n.lang) — это прямое требование модерации.
Как игрок попадает в игру
Путь игрока почти всегда один и тот же: каталог или поиск → карточка игры → запуск прямо на странице. Игра открывается по адресу вида https://yandex.ru/games/app/XXXXXX, где числовой идентификатор выдаётся платформой.
Ключевой технический факт: ваша игра запускается не «на своей странице», а внутри страницы каталога — платформа загружает её в отдельный фрейм и общается с ней через SDK. Из этого вытекает целая цепочка последствий, которые в сумме объясняют половину требований к играм:
- Игра не должна зависеть от URL, по которому она открыта (требование 1.18). Никаких «прочитать параметр из адресной строки» и никаких абсолютных ссылок на файлы, лежащие на серверах Яндекса (требование 1.7).
- Обычный локальный
index.html, открытый двойным кликом, не увидит SDK: рядом нет платформы, с которой он должен связаться. Для локальной разработки существует отдельный инструмент — прокси@yandex-games/sdk-dev-proxy, ему посвящена отдельная глава. - Платформа сама управляет паузами игры и сама показывает рекламу поверх неё.
Важно
Платформа автоматически показывает полноэкранную рекламу на старте всех игр. У этого показа нет колбэков — вы не узнаете о нём напрямую. Единственный корректный способ отреагировать — подписаться на события game_api_pause и game_api_resume и на паузе гасить звук и останавливать игровой цикл. Игры, у которых музыка играет поверх стартовой рекламы, регулярно получают отказ по пункту 4.7.
Минимальный каркас, из которого стоит начинать любой проект, выглядит так:
<!DOCTYPE html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Моя игра</title>
<!-- Yandex Games SDK -->
<script src="/sdk.js"></script>
</head>
<body>
<canvas id="game"></canvas>
<script>
YaGames.init().then((ysdk) => {
window.ysdk = ysdk;
// Платформа ставит игру на паузу, например на время рекламы.
ysdk.on('game_api_pause', () => {
// остановить игровой цикл и приглушить звук
});
ysdk.on('game_api_resume', () => {
// вернуть звук и продолжить цикл
});
// Вызывается, когда всё загружено и игрок уже может действовать.
ysdk.features.LoadingAPI?.ready();
});
</script>
</body>
</html>Это ещё не игра, но это уже правильная точка входа: подключение SDK, инициализация, реакция на паузу и сигнал готовности. Детали каждого шага — в главах про SDK и жизненный цикл.
Где физически лежит игра
Основной и рекомендуемый вариант — архив на серверах Яндекса. Вы собираете игру в ZIP и загружаете его в Консоли разработчика. Платформа сама раздаёт файлы, сама обслуживает трафик, вам не нужен ни хостинг, ни CDN, ни домен.
К архиву предъявляются жёсткие формальные требования — проверка на них происходит ещё до модерации:
| Требование | Значение |
|---|---|
| Формат | ZIP-архив |
| Корень архива | ровно один файл index.html |
| Размер содержимого до сжатия | не более 100 МБ (пункт 1.21) |
| Имена файлов и папок | без пробелов и кириллических символов (пункт 1.22) |
| Количество архивов | одновременно прикреплён только один; повторная загрузка заменяет предыдущий |
Второй вариант — размещение на своём домене через iframe. Здесь важно не поддаться распространённому мифу: это не равноправная альтернатива «на выбор», а исключение. Документация прямо рекомендует хранить игры на сервере Яндекса и допускает iframe, если игре нужна сложная серверная архитектура (например, для мультиплеера). Подключение согласуется индивидуально: нужно написать в чат поддержки и указать название игры, аккаунт разработчика, ссылку на игру по https и причину, по которой архив не подходит.
От выбора зависит одна строчка, которую чаще всего пишут неправильно, — путь к SDK:
<!-- Игра залита архивом на сервер Яндекса — относительный путь -->
<script src="/sdk.js"></script>
<!-- Игра размещена на своём домене — абсолютный путь -->
<script src="https://sdk.games.s3.yandex.net/sdk.js"></script>Частая ошибка
Если в вашем туториале, шаблоне или подсказке нейросети написано https://yandex.ru/games/sdk/v2 — это устаревший лоадер. Адрес всё ещё отвечает, но требование 1.19.1 обязывает использовать актуальный загрузчик, и сборка со старым путём получит отказ. Проверить можно на debug-панели: у актуального лоадера она показывает IT, у старого — IF. Проверено в сентябре 2026 года.
Ещё одно ограничение, о котором лучше узнать заранее: сетевые запросы к внешним хостам не запрещены, но проходят через белый список CSP в Консоли — каждый домен нужно заявить и обосновать. Разрешены только https и wss, без путей, портов и IP-адресов. И основной объём данных игры всё равно должен лежать в архиве, а не подгружаться со стороны.
Из чего складывается доход
Источников дохода на платформе два, и они независимы друг от друга.
Реклама. Показы рекламных блоков через Рекламную сеть Яндекса (внутренняя монетизация, работает по модели аукциона в реальном времени) и через сторонние сети на международном домене (внешняя монетизация). Форматов три:
| Формат | Как работает | Кто инициирует |
|---|---|---|
| Полноэкранный блок | Полностью перекрывает игру; уместен на переходах между уровнями и экранами | Платформа на старте + вы из кода |
| Видео с вознаграждением | Игрок смотрит добровольно в обмен на награду | Только вы, по действию игрока |
| Sticky-баннер | Постоянно висящий баннер | Платформа; управление из кода включается отдельно в Консоли |
Инап-покупки. Внутриигровые товары, оплачиваемые через SDK платформы. Здесь тоже есть жёсткое правило: платежи проводятся только средствами SDK (пункт 1.4), а название и иконку внутренней валюты нужно брать из каталога товаров автоматически, а не зашивать в игру (пункт 1.13.2).
Чтобы что-то из этого заработало, нужен договор. Для компаний и ИП в России это единая лицензионная схема — реклама и покупки подключаются одним договором прямо в Консоли; в остальных случаях подключение идёт через РСЯ. Подписать договор и получать выплаты может только совершеннолетний. Договор требуется до отправки игры на модерацию.
Осторожно
Сам SDK для публикации обязателен, а вот вызовы рекламы из кода — нет: документация называет их рекомендуемой, но не обязательной опцией. При этом доход зависит от популярности игры — рейтинга, ежедневной аудитории, времени в игре и возвращаемости. Никакая интеграция сама по себе не гарантирует ни выручки, ни удачного прохождения модерации. Любые «средние доходы на игру», которые вы встретите в интернете, — чужой опыт, а не свойство платформы.
Сводка по деньгам живёт в Консоли в разделе «Общий доход»: суммы по каждой игре и итог, с разбивкой на рекламу и покупки в выгружаемом отчёте. Цифры там показываются без учёта налогообложения и не являются офертой.
Устройства и платформы
При заполнении черновика вы выбираете, на каких платформах показывать игру. От этого зависят и требования, и набор промо-материалов.
| Платформа | Особенности |
|---|---|
| Десктоп | Мышь и клавиатура; самая предсказуемая среда |
| Мобильные (Android, iOS) | Выбор ориентации; для iOS в Консоли требуется Apple Team ID |
| ТВ | Управление пультом, фокус на элементах, отдельные требования по адаптации; в SDK есть событие HISTORY_BACK, работающее только на ТВ |
Для мобильных задаётся ориентация: портретная, альбомная или любая. Если выбрана конкретная, SDK сам показывает встроенную заглушку «поверните экран» в неподходящей ориентации — своё решение изобретать не нужно.
Определить устройство в рантайме можно через SDK:
// 'desktop' | 'mobile' | 'tablet' | 'tv'
const type = ysdk.deviceInfo.type;
if (ysdk.deviceInfo.isTV()) {
enableRemoteControlNavigation();
} else if (ysdk.deviceInfo.isMobile()) {
enableTouchControls();
}Отдельно стоит помнить требование 1.20: игра должна работать в Яндекс Браузере, Chrome, Firefox, Opera и Safari, в мобильном приложении Яндекса, на Android 5.0+, iOS 9.0+ и Android TV. Это не абстрактный список — минимум одну реальную проверку на телефоне стоит делать до отправки на модерацию.
Консоль разработчика и черновик
Консоль (games.yandex.ru/console) — рабочее место разработчика: там заводятся игры, загружаются архивы, подключается монетизация, отправляются заявки на модерацию и смотрится статистика. На панели управления видны основные метрики игры: рейтинг, число игроков, среднее время игры и время до срабатывания Game Ready, а также распределение игроков по странам и устройствам.
Жизненный цикл игры выглядит так:
- Создать игру и черновик — рабочую версию, которую видите только вы.
- Загрузить архив, заполнить метаданные: описание, языки, категории, промо-материалы (иконка, обложка, скриншоты, видео геймплея).
- При необходимости заявить внешние хосты на вкладке CSP и настроить страны распространения.
- Отправить на модерацию.
- Получить публикацию или отказ.
Режим черновика — самый недооценённый инструмент платформы. Игра из черновика запускается по реальному адресу на yandex.ru/games и живёт как настоящая: показывается настоящая реклама, авторизация идёт через Яндекс ID, данные игрока и лидербордов сохраняются на сервере, каталог товаров подтягивается с сервера, покупки обрабатываются по-настоящему. Доступ к черновику есть только у вашего аккаунта разработчика.
Совет
Открывайте черновик с debug-панелью (кнопка в Консоли или параметр debug-mode=16 в адресе игры). Панель показывает, какой лоадер SDK подключён, сработал ли Game Ready и что происходит с рекламой. Пять минут в ней экономят дни: модерация бывает двух видов — полная, с проверкой сборки, и контентная, только по промо-материалам, и после каждого отказа период ожидания до следующей попытки удваивается.
Заявленные сроки проверки на момент написания главы — 3–5 рабочих дней для полной модерации и 1–2 для контентной, но сам Яндекс предупреждает, что при высокой нагрузке сроки бывают больше. Планируйте релиз с запасом и не рассчитывайте на конкретную дату.
Что дальше
Теперь у вас есть карта: игра живёт архивом на сервере Яндекса, запускается во фрейме внутри каталога, общается с платформой через SDK, зарабатывает на рекламе и покупках и проходит путь «черновик → модерация → публикация». Дальше мы спускаемся с высоты птичьего полёта к практике — соберём рабочее окружение, поставим Claude Code, научимся запускать игру локально через официальный прокси и увидим SDK живьём, а не в теории.