Серверная программа для сервисов PluginYG. Сейчас backend используется для модуля покупок: каталог товаров, обработка заказов, платежные callback от платформ и выдача покупок в игру.
- Каталог товаров для PluginYG модуля Payments.
- Жизненный цикл заказа:
pending,paid,consumed,failed. - Проверка signed-покупок Yandex Games через секретный ключ.
- Поддержка платежных уведомлений VK Games и Одноклассников.
- Заготовка для платежных уведомлений CrazyGames / Xsolla.
- Раздача картинок товаров через
/images/.... - Запуск как обычное Node.js приложение.
- Dockerfile для контейнерного размещения.
Поддерживаются:
- Managed Node.js hosting, например Render или Railway.
- Docker hosting.
- VDS/VPS с Node.js, PM2, nginx и HTTPS.
Serverless/edge-сервисы вроде Cloudflare Workers, Netlify Functions и Vercel Functions пока не поддерживаются. Для них нужен отдельный runtime adapter и другое хранилище заказов. Зарубежные managed-сервисы удобны для тестов, но для российской аудитории могут быть нестабильны из-за блокировок, замедлений, санкционных ограничений... Для релиза на российскую аудиторию рекомендуется VDS/VPS с хорошей доступностью из России.
Эта инструкция нужна, чтобы: подготовить чистый Linux/VDS-сервер развернуть на нём серверную программу проксировать WebSocket и HTTP через nginx Аренда сервера Рассмотрим на примере сервиса FirstVDS. Для развертывания серверной программы достаточно самого дешевого тарифа с минимальными мощностями. При настройке тарифа, ОС необходимо выбрать Ubuntu. Для наибольшей стабильности лучше выбрать версию 22.04. Предустановленное ПО — не выбрано.
После создания виртуальной машины, вы получите IP-адрес сервера, логин (обычно root). Чтобы получить или создать пароль, следуйте инструкции сервиса. Настройка домена Для работы требуется домен. Использование только IP-адреса в продакшене не подойдёт, так как невозможно корректно настроить HTTPS. Вариант 1: Если у вас уже есть сайт Если у вас есть сайт (например, размещённый на хостинге), можно использовать его домен. Для адреса к серверу игры рекомендуется создать поддомен. Создание поддомена В разных сервисах для хостинга при создании поддомена могут быть различия, но суть одна. Пример — перейдите в панель управления доменом Откройте раздел DNS или домены Добавьте запись: Тип: A Имя: api Значение: IP-адрес вашего сервера
(Изменения DNS могут применяться от 5 минут до 1 часа) Вариант 2: Если домена нет Если у вас нет собственного домена, его необходимо приобрести у любого регистратора, например Beget или FirstVDS. После покупки вы получите доступ к панели управления DNS. Привязка домена к серверу В DNS панели создайте запись: Тип: A Имя: @ Значение: IP-адрес вашего сервера Для поддомена (рекомендуется): Тип: A Имя: api Значение: IP-адрес вашего сервера (Изменения DNS могут применяться от 5 минут до 1 часа)
Настройка вспомогательных программ Чтобы выполнять команды на сервере, для Windows часто используют PuTTY. Порядок действий для подключению к серверу через PuTTY: Установить PuTTY Открыть putty.exe (находится в папке, в которую была установлена программа) В поле Host Name (or IP address) указать IP сервера Порт: 22 Тип соединения: SSH Нажать Open При первом подключении согласиться с предупреждением Ввести логин Ввести пароль. Чтобы вставить текст из буфера обмена, нажмите ПКМ. Пароль не будет видно, это нормально. Нажимаем Enter и входим в систему. Чтобы работать с файлами сервера, для windows часто используют WinSCP. Чтобы подключиться к серверу через WinSCP, также как с PuTTY, но в отдельном меню, введите IP (имя хоста), имя пользователя (имя администратора), пароль, порт 22. Можно сохранить пресет для подключения, чтобы в следующий раз подключится без ввода параметров. В WinSCP сверху есть поле поле Адрес, туда можно вписать путь, чтобы быстро перейти к определённой папке. В WinSCP, чтобы открыть файл в редакторе текста, нажмите ПКМ по файлу → Править → Настройки. Откроется раздел настроек «Редактор». Выберите программу для редактирования. Обычно удобно использовать Notepad++ или SublimeText. Ожидается, что следуя данной документации, вводить команды вы будете в PuTTY, а с файлами работать через WinSCP. Когда в данной документации вы видите две команды подряд на разных строках, это означает, что их необходимо выполнить по очереди, раздельно. Настройка VDS Поочередно выполните следующие команды: Обновление пакетов: apt update && apt upgrade -y
Установка базовых утилит: apt install -y curl wget ufw git unzip
Команда для проверки установленных dotnet пакетов: dotnet --list-runtimes
Установка Node.js и wscat: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs sudo npm install -g wscat
Настройка firewall Важно! Сначала всегда разрешать 22, только потом включать firewall.
Разрешить SSH и веб-порты: sudo ufw allow 22 sudo ufw allow 80 sudo ufw allow 443
Включить UFW: sudo ufw enable
Проверить статус: sudo ufw status Ожидается примерно такое состояние: 22 ALLOW 80 ALLOW 443 ALLOW Отключение автообновления пакетов Откройте каталог: /etc/apt/apt.conf.d/ Откройте файл: 50unattended-upgrades В секцию blacklist добавьте: Unattended-Upgrade::Package-Blacklist { "dotnet-runtime-8.0"; "aspnetcore-runtime-8.0"; "nodejs"; "npm"; };
Загрузка программы на сервер Импортируйте backend из github репозитория: cd /var/www git clone https://github.com/JustPlay-Max/PluginYGBackend.git pluginyg-backend
Если из репозитория клонировать не удалось, импортируйте вручную через WinSCP.
На VDS создайте папку /var/www/pluginyg-backend Скачайте пакет с github и перенесите файлы в созданную папку.
В импортированных файлах найдите config.example.json. Скопируйте его файл config.example.json Назовите новый файл config.json и откройте его Найдите строку "publicBaseUrl": "https://your-backend-domain.com", Измените значение https://your-backend-domain.com на ваш адрес с поддоменом, который вы создавали.
Выполните команды: cd /var/www/pluginyg-backend npm install npm run build
Установка pm2 Выполните для установки pm2: sudo npm install -g pm2
Запустить backend на внутреннем порту 8090: cd /var/www/pluginyg-backend PORT=8090 pm2 start dist/server.js --name pluginyg-backend
Вы должны увидеть процесс pluginyg-backend со статусом online.
Проверьте backend локально на сервере: curl http://localhost:8090/health
Должен вернуться JSON примерно такой: {"name":"PluginYG Backend","version":"0.2.0", ...}
Сохраните текущий процесс: pm2 save
Настроить автозапуск PM2: pm2 startup
После выполнения команда может:
- сразу настроить автозапуск, если пользователь работает под root;
- или вывести команду с sudo, которую нужно скопировать и выполнить вручную.
После настройки автозапуска сохранить список процессов: pm2 save
Проверка: pm2 status Вы должны увидеть процесс pluginyg-backend со статусом online.
Затем: curl http://localhost:8090/health Должен вернуться JSON примерно такой: {"name":"PluginYG Backend","version":"0.2.0", ...}
Установка и настройка Nginx, домена и HTTPS HTTPS настраивается с помощью SSL-сертификата. Для этого используется Certbot, который автоматически получает и настраивает сертификат от Let’s Encrypt. Установка Nginx sudo apt update sudo apt install -y nginx Проверка: sudo systemctl status nginx Создайте файл на сервере: /etc/nginx/sites-available/pluginyg-backend Вставьте содержимое: server { listen 80; server_name your-backend-domain.ru;
location / {
proxy_pass http://127.0.0.1:8090;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
}
}
Замените your-backend-domain.ru на ваш адрес
Выполните команды: sudo ln -s /etc/nginx/sites-available/pluginyg-backend /etc/nginx/sites-enabled/pluginyg-backend
sudo nginx -t sudo systemctl reload nginx
Проверка: curl http://your-backend-domain.ru/health
Ожидаемый результат: JSON, где есть: "name": "PluginYG Backend" Настройка HTTPS Выпустить сертификат для поддомена: sudo certbot --nginx -d your-backend-domain.ru В процессе certbot может спросить email и согласие с условиями. Если спросит про redirect HTTP -> HTTPS, выбирай redirect.
Проверить HTTPS: curl your-backend-domain.ru
Ожидаемо JSON с: "name": "PluginYG Backend"
Проверить автообновление сертификата: sudo certbot renew --dry-run
Ожидаемо что-то вроде: Congratulations, all simulated renewals succeeded
После этого backend на VDS будет доступен по HTTPS.
Настройка каталога товаров
В Unity в настройках модуля Payments нужно:
- Включить backend;
- Указать URL серверной программы, например https://api.your-backend-domain.ru
Товары можно описывать двумя способами:
- в массиве
productsвнутриconfig.json - отдельными
.jsonфайлами в папке products
Для примера смотрите файл test.json в папке products. Один такой файл - это один продукт для игры. Когда файл test.json для примера вам уже не будет нужен, удалите его.
В файле вы найдете поля продукта такие как название товара, описание, цена и т.д. Заполните поля в соответствии с товаром вашей игры.
Описание полей продукта:
id- внутренний ID товара в PluginYG. По нему игра вызывает покупку.type- тип товара:consumable,nonConsumableилиsubscription(оставьте consumable).title- название товара для backend-каталога.description- описание товара для backend-каталога.imageURI- имя картинки изpublic/imagesили полный URL.price- базовая цена товара для backend-каталога и платформ, которым нужна цена из backend.providers- настройки товара для конкретных платформ.
Backend поддерживает переводы названия товара, описания товара и названия валюты на русском и английском языках. Вы можете заполнить только стандартные title и description, тогда в игру вернётся название и описание товара исключительно на английском языке. Заполните поля titleRU и descriptionRU, тогда вернётся название и описание товара на русском языке, если он выбран в игре.
Каждая платформа внутри товара описывается в providers. В классе платформы можно переопределить поля. Например, для платформы vkbridge записать поле "price": 10. Тогда на платформе VK цена будет равняться 10, а на других платформах, у которых переопределение цены отсутствует, будет использоваться значение из базового поля.
Следите, чтобы в файле было правильное json форматирование. При наличии ошибок backend будет работать некорректно.
В файле config.json, который мы создавали ранее, настройте значения для следующих полей:
currencyTitle- название валюты. Оставьте значение пустым, если не используется в игре.currencyTitleRU- название валюты на русском языке. Оставьте значение пустым, тогда всегда будет использоваться значение из currencyTitle.currencyImageURI- имя картинки валюты изpublic/imagesили полный URL. Замените картинку на свою, или оставьте значение пустым если иконка валюты в игре не используется.
В файле config.json также есть переопределение полей для платформ. Например, по умолчанию для платформы VK, currencyTitle переопределяет значение на Votes, потому что на платформе VK оплата производится за голоса.
Для платформы переопределение названия валюты и иконки валюты не будет работать, так как эти данные берутся напрямую из SDK Яндекс Игр, а не из backend. Тоже самое касается других данных, таких как картинка продукта, название, описание и цена. Эти данные берутся из каталога товаров, которые создаются в консоли разработчика Яндекс Игр.
О других настройках для каждой платформы смотрите в разделе документации конкретной платформы.
После обновления конфигов, чтобы backend на VDS подтянул изменения, выполните следующие команды:
cd /var/www/pluginyg-backend pm2 restart pluginyg-backend Как обновлять backend на VDS Если вышла новая версия backend, выполните следующие команды:
cd /var/www/pluginyg-backend git pull npm install npm run build pm2 restart pluginyg-backend
Проверьте есть ли обновление модуля Payments для PluginYG в Unity и обновите, если есть. Загрузите новый билд на хост для платформы. Может потребоваться обновление кеша браузера, чтобы увидеть новый билд игры, а не старый после его обновления. Для этого на странице с игрой нажмите CTRL + F5 или очистите КЕШ в настройках браузера.