Пока игра лежит у вас в папке, она сама по себе: показывает картинки, считает очки и ничего не знает про внешний мир. В каталоге ей придётся разговаривать с платформой — сообщать, что загрузка закончилась, вызывать рекламу, сохранять прогресс, узнавать язык игрока. Этот разговор и есть SDK.
Расшифровывается как «набор средств разработки», но пугаться нечего: со стороны вашего кода это одна подключённая библиотека и несколько вызовов.
Почему его нельзя пропустить
Первым же пунктом в требованиях платформы стоит:
Пункт 1.1. В игру встроен SDK Яндекс Игр.
Это значит буквально следующее: игра без SDK не проходит модерацию. Даже идеальная, даже если вы не хотите ни рекламы, ни покупок, ни лидербордов. Документация отвечает на этот вопрос прямо: нет, не подключать SDK нельзя.
Заодно он делает то, что иначе пришлось бы писать руками: переход в полноэкранный режим, определение языка интерфейса, серверное время (защита от перевода часов на устройстве), сохранение прогресса на стороне Яндекса.
Подключение: одна строка
SDK подключается тегом в index.html, до всего остального кода игры:
<script src="/sdk.js"></script>Путь относительный, с одной косой чертой в начале, и это не опечатка: архив игры лежит на сервере Яндекса, и по этому адресу платформа сама отдаёт нужную версию библиотеки.
Осторожно
Файл sdk.js не нужно скачивать и класть в архив. Документация говорит об этом отдельно: подключается именно адрес, а не копия файла. Копия устареет и в какой-то момент просто перестанет работать.
Если игра размещается не в каталоге, а на вашем домене, путь нужен абсолютный:
<script src="https://sdk.games.s3.yandex.net/sdk.js"></script>Можно грузить скрипт не блокируя страницу — тогда код игры запускается после загрузки библиотеки:
<script async src="/sdk.js" onload="initSDK()"></script>Инициализация
После загрузки скрипта SDK нужно инициализировать. Объект, который вернётся, — это и есть точка входа во все возможности платформы, его принято называть ysdk:
const ysdk = await YaGames.init()Всё. Дальше ysdk живёт в вашем коде и через него вызывается остальное.
Частая ошибка
Uncaught ReferenceError: YaGames is not defined — скрипт SDK не подключён или подключён после кода, который его использует. Тег <script src="/sdk.js"> должен стоять до вызова YaGames.init().
Uncaught ReferenceError: ysdk is not defined — методы SDK вызваны раньше, чем закончилась инициализация. Сначала init(), потом всё остальное.
Два метода, без которых модерация завернёт
Подключить библиотеку мало — платформа проверяет, что вы её действительно используете. Это пункт 1.19 требований, и он разбит на части.
Game Ready: «игра загрузилась»
Когда игра готова к игре — доступно меню или сразу игровой процесс, никаких экранов загрузки — нужно сообщить об этом платформе:
const ysdk = await YaGames.init()
// Сообщаем платформе, что игра загрузилась и можно начинать играть.
ysdk.features.LoadingAPI?.ready()Вопросительный знак перед точкой — не украшение: он означает «вызови, если такой раздел есть». Так игра не упадёт, если платформа что-то поменяет.
Модерация смотрит на этот вызов через debug-панель: специальный индикатор должен смениться с фиолетового на зелёный в течение 90 секунд после запуска и ровно в тот момент, когда игрой действительно можно пользоваться.
Важно
Не привязывайте ready() к таймеру — «через три секунды после старта». Проверяют в двух сценариях: когда загрузочный экран Яндекса закрывают вручную нажатием и когда он пропадает сам. При таймере разница видна сразу, и это считается нарушением.
Разметка геймплея: «сейчас играют»
Вторая пара методов размечает, когда игрок действительно играет, а когда нет:
ysdk.features.GameplayAPI?.start() // игровой процесс идёт
ysdk.features.GameplayAPI?.stop() // игровой процесс остановленstart() вызывается, когда | stop() вызывается, когда |
|---|---|
| запускается уровень | уровень пройден или проигран |
| закрывается меню | открывается меню |
| игра снимается с паузы | игра ставится на паузу |
| закончился показ рекламы | начинается показ рекламы |
| игрок вернулся во вкладку браузера | игрок ушёл в другую вкладку |
Разметка геймплея сама по себе необязательна. Но если она есть, моменты вызова должны совпадать с описанными — «расставить для галочки» хуже, чем не расставлять вовсе: это как раз то, что модерация и ловит.
Пауза и звук: два события вместо своего кода
Требования обязывают останавливать звук при потере фокуса (пункт 1.3) и ставить игру на паузу на время рекламы (пункт 4.7). Писать это самому не нужно — платформа сама сообщает игре, когда пора остановиться:
ysdk.on('game_api_pause', () => {
pauseGame() // ваша функция: останавливает игровой цикл и музыку
})
ysdk.on('game_api_resume', () => {
resumeGame() // ваша функция: возобновляет всё обратно
})Эти два события срабатывают при показе и закрытии полноэкранной рекламы и рекламы за вознаграждение, при открытии окна покупок, при переключении вкладок браузера и при сворачивании окна. То есть закрывают сразу целый набор требований, на которых обычно и спотыкаются.
Они согласованы с разметкой геймплея: на game_api_pause платформа сама вызывает GameplayAPI.stop(), на game_api_resume — start().
Что ещё умеет SDK
| Возможность | Через что | Зачем нужно |
|---|---|---|
| Реклама | ysdk.adv.* | Доход с игры — этому посвящена следующая глава |
| Сохранение прогресса | player.setData(), player.getData() | Пункт 1.9: прогресс не теряется после перезагрузки |
| Счётчики | player.setStats(), player.incrementStats() | Для часто меняющихся чисел: очки, валюта, опыт |
| Авторизация | player.isAuthorized(), ysdk.auth.openAuthDialog() | Пункт 1.2: вход только через Яндекс ID и только по кнопке |
| Язык игрока | ysdk.environment.i18n.lang | Пункт 2.14: язык определяется автоматически |
| Лидерборды | ysdk.leaderboards.setScore() | Таблица рекордов — соревновательная механика |
| Покупки | ysdk.getPayments() | Пункт 1.4: платежи только через SDK |
| Серверное время | ysdk.serverTime() | Ежедневные награды, которые не обмануть переводом часов |
| Полноэкранный режим | screen.fullscreen | Кнопка полноэкранного режима внутри игры |
Ничего из этого не обязательно для первой игры, кроме сохранений — если в ней есть прогресс.
Сохранение прогресса
Самая частая после рекламы причина обращаться к SDK. Выглядит так:
const player = await ysdk.getPlayer()
// Сохранить.
await player.setData({ level: 7, coins: 120 })
// Прочитать обратно.
const data = await player.getData(['level', 'coins'])Для чисел, которые меняются постоянно — счёт, монеты, опыт — в SDK есть отдельные методы setStats() и incrementStats(): они дешевле и рассчитаны именно на частые изменения.
Важно
Требование 1.2.2 говорит, что играть можно и без входа в аккаунт, и прогресс при этом всё равно должен сохраняться. Простое решение: писать прогресс и в SDK, и в память браузера, а при запуске брать то, что новее. Неавторизованный игрок не потеряет прогресс, а авторизованный увидит его на другом устройстве.
Как заказать это Claude Code
Нейросети документация Яндекс Игр известна не целиком, поэтому не полагайтесь на память модели — давайте ссылку и точные формулировки. Рабочая постановка задачи:
Подключи к игре SDK Яндекс Игр по документации:
https://yandex.ru/dev/games/doc/ru/sdk/sdk-about
Требования:
1. Тег <script src="/sdk.js"></script> в index.html до кода игры.
2. Инициализация: const ysdk = await YaGames.init().
3. Вызов ysdk.features.LoadingAPI?.ready() в момент, когда игра
реально готова к взаимодействию, а не по таймеру.
4. Разметка геймплея GameplayAPI.start() и stop() в моменты
из раздела «Геймплей» документации.
5. Подписка на события game_api_pause и game_api_resume:
по паузе останавливать игровой цикл и звук, по resume — возобновлять.
6. Прогресс сохранять через player.setData(), при старте читать
через player.getData(), запасной вариант — localStorage.
Не придумывай методы по памяти. Если чего-то нет в документации
по ссылке — скажи об этом, а не подставляй похожее название.Последний абзац здесь не для вежливости. Названия методов у платформ похожи и нейросети их путают: например, метод рекламы за вознаграждение называется showRewardedVideo(), а не так, как назывался бы по аналогии с полноэкранным.
Как проверить, что всё подключено правильно
Debug-панель
Откройте игру в Консоли кнопкой «Открыть с debug-панелью» или добавьте в адрес игры ?debug-mode=16. Панель покажет два важных индикатора:
| Что видно | Что означает |
|---|---|
IT | Загрузчик SDK подключён правильно |
IF | Используется старый способ подключения — переделать по документации |
| Индикатор Game Ready позеленел | ready() вызван |
| Индикатор так и остался фиолетовым | Вызова нет — модерация это увидит |
Запуск с локального сервера
Проверять SDK, гоняя архив в Консоль по кругу, мучительно. Есть официальный пакет, который поднимает игру локально, но с работающим SDK:
npx @yandex-games/sdk-dev-proxy -p путь-до-папки-с-игрой --app-id=ID-черновикаДва режима:
- Как на реальной платформе. Нужны аккаунт разработчика и черновик игры. Показывается настоящая реклама, работает авторизация, данные сохраняются на сервере. Подходит для финальной проверки перед отправкой.
- Отладочный (ключ
--dev-mode). Ни аккаунт, ни черновик не нужны: все вызовы SDK подменяются заглушками. Подходит, пока вы просто пишете логику и перезагружаете страницу каждые полминуты.
Короткий чек-лист
-
<script src="/sdk.js"></script>стоит вindex.htmlдо кода игры - Файл
sdk.jsв архив не положен -
YaGames.init()вызывается после загрузки скрипта -
LoadingAPI.ready()вызывается в момент реальной готовности игры - Если есть разметка геймплея —
start()иstop()в правильных моментах - Подписка на
game_api_pauseиgame_api_resumeостанавливает звук и игру - Прогресс сохраняется и переживает перезагрузку страницы
- На debug-панели видно
ITи зелёный Game Ready
Что дальше
SDK подключён — значит, игра умеет разговаривать с платформой. Самая доходная часть этого разговора — реклама, и следующая глава как раз о ней: какие бывают форматы, как их вызывать и за какие ошибки в показе рекламы заворачивают игры.