PluginYG2 для Unity: подробная инструкция по Яндекс Играм

PluginYG2 для Unity — один из самых удобных способов подключить игру к Яндекс Играм без ручной работы с SDK. Плагин берёт на себя рекламу, облачные сохранения, авторизацию, таблицы лидеров, покупки, локализацию и другие платформенные функции, а нужные возможности подключаются отдельными модулями.

В этой инструкции разберём Plugin Your Games 2.0 с нуля: от установки в проект до готовой WebGL-сборки. Материал ориентирован на разработчика, который впервые подключает Яндекс Игры к Unity и хочет понимать, что именно он делает, а не просто повторять набор действий.

Важно: PluginYG2 заметно отличается от старого PluginYG 1.x. В первой версии многие проекты строились вокруг префаба YandexGame. Во второй версии такого обязательного префаба больше нет, а функциональность разбита на модули. Если у вас старый проект, не переносите шаги из руководств по 1.x буквально. Официальная документация отдельно описывает миграцию на 2.0.

Если вам нужна именно старая версия, у нас уже есть отдельная инструкция: «Подключение PluginYG в Unity». Эта статья посвящена именно PluginYG2.

Что такое PluginYG2 и зачем он нужен

Plugin Your Games 2.0 — бесплатный открытый плагин для Unity, который связывает игру с API игровых площадок. Основной бесплатной платформой является Яндекс Игры. Архитектура модульная: реклама, сохранения, лидерборды, платежи и другие системы добавляются только тогда, когда они реально нужны проекту.

полноэкранная реклама;
реклама за вознаграждение;
облачные сохранения;
авторизация и данные игрока;
таблицы лидеров;
внутриигровые покупки;
локализация;
метрика, отзывы, ссылки на другие игры и дополнительные модули.

По официальной документации поддерживаются Unity 2021.3.18+, Unity 2022.3+, Unity 2023.2+ и Unity 6. Перед импортом в проекте не должно быть ошибок компиляции, а файлы самого плагина после установки не рекомендуется переносить вручную.

Шаг 1. Установка PluginYG2

Самый простой вариант — установить PluginYG2 из Unity Asset Store. После импорта появится приветственное окно и новое меню плагина в Unity. Основные инструменты находятся в разделе Tools → YG2.

Откройте окно настроек PluginYG2 и сначала проверьте раздел Basic Settings. Для обычной публикации в Яндекс Играх платформой должна быть выбрана Yandex Games. Если при первом импорте вы согласились применить рекомендуемые настройки, часть параметров уже будет заполнена автоматически.

Документация: официальное начало работы PluginYG2.

Шаг 2. Разберитесь с модульной системой

В PluginYG2 не нужно тащить в проект весь функционал сразу. Откройте инструмент контроля версий модулей и импортируйте только те системы, которые действительно используются в игре.

Для типичной игры на Яндекс Играх минимальный набор часто выглядит так:

InterstitialAdv — полноэкранная реклама;
RewardedAdv — реклама за вознаграждение;
Authorization — авторизация и данные игрока;
Storage — облачные сохранения;
Leaderboards — таблицы лидеров;
Localization — локализация;
Payments — внутриигровые покупки, если они нужны.

У каждого модуля создаётся собственный define с окончанием _yg. Это удобно, если часть вашего кода должна компилироваться только при наличии конкретной функции.

Шаг 3. Основы работы с кодом

Основной API PluginYG2 находится в пространстве имён YG. Поэтому в скриптах, которые обращаются к плагину, добавьте:

using YG;

Большинство вызовов выполняется через статический класс YG2. Например, полноэкранная реклама вызывается одной строкой:

YG2.InterstitialAdvShow();

При этом писать код вообще не обязательно во всех случаях. Компонент EventsYG2 позволяет назначать многие методы через Inspector, примерно как обычные события кнопки Unity UI. Для простого проекта это хороший способ быстро подключить рекламу или другие функции без отдельного скрипта.

Шаг 4. Полноэкранная реклама

Импортируйте модуль InterstitialAdv. Полноэкранную рекламу логично показывать в естественных паузах игры: после уровня, между забегами, при переходе в меню. Не вызывайте её в момент активного управления игроком.

using YG;

public class AdsExample
{
    public void ShowInterstitial()
    {
        YG2.InterstitialAdvShow();
    }
}

У модуля есть события открытия, закрытия и ошибок. Кроме того, PluginYG2 предоставляет единое состояние паузы игры через YG2.onPauseGame и YG2.isPauseGame. Это особенно важно на Яндекс Играх, потому что автоматическую рекламу при старте платформа может показать сама, и её состояние надёжнее отслеживать именно через событие паузы.

Полезный раздел: Interstitial Adv.

Шаг 5. Реклама за вознаграждение

Rewarded-реклама отличается от обычной тем, что игрок сам соглашается посмотреть ролик ради конкретной награды. Например: получить дополнительные монеты, воскреснуть, открыть бонус или продолжить уровень.

Главное правило — выдавать награду только после подтверждения успешного просмотра. Не начисляйте бонус сразу после нажатия кнопки «Посмотреть рекламу».

В модуле RewardedAdv есть события открытия, закрытия и успешного получения награды. Для визуального подключения можно использовать готовые компоненты и EventsYG2, а для собственного интерфейса — API плагина.

Документация: Rewarded Adv.

Шаг 6. Облачные сохранения

Для полноценной системы сохранений импортируйте Storage. Для Яндекс Игр модуль зависит от Authorization. В настройках Storage для Яндекс Игр рекомендуется использовать облачное сохранение.

Свои данные добавляются в partial-класс SavesYG:

namespace YG
{
    public partial class SavesYG
    {
        public int coins = 0;
        public int level = 1;
        public bool tutorialCompleted = false;
    }
}

После этого обращаться к данным можно через YG2.saves:

YG2.saves.coins += 100;
YG2.saves.level = 5;
YG2.SaveProgress();

При запуске PluginYG2 сам загружает данные в YG2.saves. В обычном сценарии вручную вызывать загрузку не нужно. Сохраняйте прогресс в важных точках: после завершения уровня, покупки, изменения настроек или получения значимой награды. Не стоит отправлять сохранения каждый кадр или после каждого незначительного действия.

Для словарей, многомерных массивов и более сложных структур документация рекомендует Newtonsoft JSON. Нужно учитывать, что это увеличивает размер WebGL-билда примерно на 2 МБ.

Документация: Storage.

Шаг 7. Авторизация игрока

Модуль Authorization нужен не только для кнопки входа. Через него доступны имя, аватар и статус пользователя, а также от него зависят другие системы — например лидерборды и платежи.

if (YG2.player.auth)
{
    Debug.Log(YG2.player.name);
}

Данные игрока находятся в YG2.player. Если пользователь не авторизован, имя может возвращаться как unauthorized, а для анонимного пользователя — anonymous.

Документация: Authorization.

Шаг 8. Таблицы лидеров

Сначала создайте таблицу в консоли Яндекс Игр и запомните её техническое название. Затем импортируйте модуль Leaderboards.

Запись результата:

YG2.SetLeaderboard("BestScore", 1500);

Важно: PluginYG2 запишет переданное значение даже если оно хуже предыдущего. Сравнение рекорда нужно делать в своей игровой логике. Кроме того, запрос записи нельзя отправлять чаще одного раза в секунду.

Если хотите показывать таблицу прямо в игре, в модуле есть готовый компонент Leaderboard YG и префабы. Для простого режима достаточно технического имени и текстового поля. В Advanced-режиме можно выводить места, аватары, имена и результаты отдельных игроков.

Документация: Leaderboards.

Шаг 9. Локализация

Язык платформы доступен через YG2.lang. Формат — код языка: ru, en, tr и так далее.

Debug.Log(YG2.lang);
YG2.SwitchLanguage("en");

При ручном переключении языка вызывается событие onSwitchLang. Если в вашем проекте уже есть своя система локализации, необязательно переносить всю логику на PluginYG2 — можно использовать язык SDK как источник первоначального выбора.

Документация: Localization.

Шаг 10. Внутриигровые покупки

Для покупок нужен модуль Payments. На стороне Яндекс Игр необходимо подключить внутриигровые покупки и создать товары в консоли. Для Яндекс Игр при использовании платежей обязательно продумайте надёжное облачное хранение прогресса.

После успешной покупки PluginYG2 вызывает событие YG2.onPurchaseSuccess и передаёт ID товара. Именно по этому ID ваша игра должна решить, что выдать пользователю.

Отдельное внимание уделите необработанным покупкам. Ситуация возможна, когда платёж прошёл, но игра закрылась до выдачи награды. Такие покупки нужно консумировать. PluginYG2 предоставляет методы YG2.ConsumePurchases и YG2.ConsumePurchaseByID, а также готовый компонент для автоматической обработки.

Это один из тех разделов, где не стоит ограничиваться только примером из статьи. Перед релизом обязательно пройдите официальную документацию: Payments.

Как тестировать PluginYG2 прямо в Unity

Сильная сторона PluginYG2 — симуляция платформенных функций в Editor. Можно проверить рекламу, задержку её открытия, пользователя, лидерборды, покупки и другие данные без постоянной загрузки WebGL-билда на площадку.

Это не отменяет тестирование настоящего билда. Симуляция нужна для игровой логики и интерфейса, а финальная проверка SDK должна происходить в окружении Яндекс Игр.

Сборка WebGL для Яндекс Игр

Когда основные модули настроены, переключите проект на WebGL и соберите игру. PluginYG2 хранит номер сборки и добавляет его в название ZIP-архива. Это удобно, когда вы несколько раз загружаете новый билд в консоль и хотите понимать, какая версия сейчас тестируется.

Для быстрых тестовых сборок в Unity можно использовать более быстрый режим Code Optimization, а для финальной публикации — оптимизацию на скорость выполнения с LTO. Конкретные названия пунктов зависят от версии Unity.

Типичные ошибки при работе с PluginYG2

Использовать инструкцию для PluginYG 1.x как инструкцию для 2.x. API и структура проекта изменились.
Импортировать все модули подряд. Подключайте только нужные системы.
Перемещать папки PluginYG2 вручную. Разработчик плагина прямо предупреждает этого не делать.
Сохранять прогресс слишком часто. Облачные сервисы имеют ограничения на частоту запросов.
Выдавать награду за rewarded-рекламу до подтверждения просмотра.
Забывать про паузу игры во время рекламы.
Не проверять необработанные покупки. Игрок может заплатить и не получить товар, если этот сценарий не реализован.
Тестировать только в Unity Editor. Финальные SDK-сценарии нужно обязательно проверять в черновике игры на Яндекс Играх.

Что я бы подключал в новом проекте в первую очередь

Если вы только начинаете интеграцию, не пытайтесь за один вечер подключить весь SDK. Практичнее идти поэтапно:

установить PluginYG2 и собрать пустой WebGL-билд;
подключить InterstitialAdv и RewardedAdv;
добавить Storage и проверить сохранение между перезапусками;
подключить Authorization;
добавить лидерборды, если они действительно нужны игре;
только после стабильной базовой интеграции заниматься платежами, дополнительными модулями и более сложной логикой.

PluginYG2 без кода: когда это имеет смысл

Через EventsYG2 и готовые префабы можно реализовать значительную часть интеграции без собственного C#-кода. Для небольшой игры это нормальный вариант. Но если проект развивается, лучше постепенно переносить критичные части в свои скрипты: так проще контролировать условия показа рекламы, сохранения, награды и обработку ошибок.

Итог

PluginYG2 для Unity заметно упрощает публикацию игры в Яндекс Играх: вместо ручной интеграции SDK вы подключаете нужные модули и работаете через единый API. Для первой рабочей версии обычно достаточно настроить платформу, рекламу, сохранения и авторизацию, после чего уже можно переходить к лидербордам, покупкам и другим возможностям.

Главное — не воспринимать плагин как «магическую кнопку». Он снимает большую часть рутинной интеграции, но правила показа рекламы, моменты сохранения, выдача наград и защита покупок всё равно остаются частью вашей игровой логики.

Официальные источники: сайт PluginYG2, документация PluginYG2 и документация Яндекс Игр. Перед публикацией проекта проверяйте актуальные требования площадки: SDK и правила модерации со временем меняются.

PluginYG2 для Unity: подробная инструкция по интеграции Яндекс Игр