Yupland Academy: как я сделал Telegram Mini App внутри Yupland

Краткое описание: В кейсе разбираю Yupland Academy, Telegram Mini App внутри игрового мира Yupland. Я сделал приложение, чтобы знакомить с Yupland через учебные модули и задания; в том же приложении доступны PvP-режимы. В статье также рассказываю о технической части, на которую ушло больше всего времени: получении и проверке Telegram initData.

Yupland представляет собой игровую экосистему. Внутри неё я сделал Yupland Academy, Telegram Mini App для знакомства с миром Yupland через учебные модули и задания. PvP-режимы доступны там же. Приложение я создал один, от первой идеи до текущего состояния.

Проект объединяет учебный маршрут, задания и игровые режимы. На главном экране собраны прогресс, опыт, уровень, бейдж и кнопка продолжения обучения. Нижнее меню открывает PvP и задания, а также разделы наград, рефералов и настроек.

Учебный прогресс виден сразу

На приложенном экране показано состояние одного профиля: 504 опыта, шестой уровень, один бейдж, 1 из 42 модулей и 2% общего прогресса. Это значения со скриншота, а не статистика всех пользователей.

Такой экран помогает быстро сориентироваться: сколько уже пройдено и куда перейти дальше. Учебный путь показан как «Дорожная карта».

Главный экран: прогресс, опыт, уровень и переход к следующему модулю.

Задания связывают контент и игру

В разделе заданий есть действия, которые знакомят с разными частями Юпленда. «Новости Юпленда», «Игровые анонсы» и «Базар Юпленда» дают по 10 опыта. В описаниях объясняется, где читать новости, узнавать об игровых событиях и искать обмен или торговлю артефактами.

Есть и задания для PvP. За первую дуэль дают 15 опыта; за матч со ставкой Duplo начисляют 25, за победу в Yupland Battle получают 30. Так опыт начисляется и за изучение мира, и за участие в игре.

Задания, которые ведут к новостям, игровым анонсам и базару.

PvP-задания и указанные в интерфейсе награды за них.

PvP в Yupland Academy

На странице PvP видны турниры с распределением 60/30/10 между призовыми местами, Yupland Battle между шестью школами, дуэли по приглашению и Quiz Battle. В каталоге игр перечислены шахматы, реверси на поле 8×8, морской бой на поле 10×10, «Четыре в ряд» и Hex. В интерфейсе шахматы отмечены как доступные; остальные карточки помечены как новинки.

В главном меню PvP находится рядом с учебным маршрутом и заданиями. По интерфейсу видно, какие игровые режимы входят в Yupland Academy.

Раздел PvP: турниры и карточки игровых режимов.

Каталог PvP-игр с подписями о доступности и новинках.

Что такое Yupland

Yupland — игровая экосистема и мир, частью которого является Yupland Academy. Yupland Academy я сделал как одну из точек знакомства с миром Yupland. Пользователь изучает модули и выполняет задания, а игровые режимы доступны в том же приложении.

В Academy обучение связано с прогрессом, XP и PvP. Так знакомство с миром Yupland продолжается через задания и игровые активности.

Самой трудной частью оказался Telegram initData

Дольше всего я разбирался с данными, которые Telegram передаёт Mini App при запуске. Их нужно получить в клиенте, передать серверу и проверить подпись. Telegram отдельно предупреждает, что initDataUnsafe нельзя считать доверенным источником; проверять нужно исходную строку initData на сервере (документация Telegram).

Путь initData: получение, передача и проверка подписи до разбора данных пользователя.

В истории проекта несколько итераций с initData касались повторного кодирования и старта приложения: значение иногда приходило закодированным дважды, а объект Telegram.WebApp появлялся позже. Адрес страницы мог измениться; после повторного открытия значение могло пропасть и из объекта Telegram, и из URL.

Я сделал несколько источников получения данных. Клиент сначала сохраняет tgWebAppData из адреса страницы во временное хранилище вкладки sessionStorage, пока другой код не очистил URL. При запросе приложение проверяет эту копию, затем Telegram.WebApp.initData, параметры URL и последнюю сохранённую копию в localStorage.

Клиент отправляет initData серверу на Hono в заголовке X-Telegram-Init-Data. Сервер обрабатывает отдельный случай двойного кодирования, собирает строку параметров и проверяет подпись HMAC-SHA-256 с помощью токена бота. Эта проверка помогает убедиться, что данные Telegram не подменили. Только после неё сервер разбирает данные пользователя.

По истории Git видно, что я возвращался к этой части с 8 по 30 мая 2026 года: исправлял передачу данных, гонки при запуске и сохранение между перезапусками. Пользователь почти не видит эту работу, хотя от неё зависит вход в приложение.

Стек проекта

Клиент использует React 19 и TypeScript, сборку выполняет Vite; состояние хранит Zustand. Сервер использует Hono и tRPC, а данные хранятся в PostgreSQL через Drizzle ORM. В потоке TMA клиент передаёт данные запуска, сервер проверяет подпись до разбора данных пользователя.

Мой технический вывод: для TMA нужно проверять весь путь initData, начиная с первого запуска и появления Telegram bridge. Проверка включает очистку URL, повторное открытие приложения и подпись на сервере. Одного успешного запуска мало.

Для меня Yupland Academy стала игровой точкой входа в экосистему Yupland. Знакомство с миром здесь связано с прогрессом, заданиями и PvP.

Коротко

• Что такое Yupland? Yupland — игровая экосистема и мир, внутри которого развивается Yupland Academy и связанные игровые механики.
• Что такое Yupland Academy? Telegram Mini App, которую я сделал как точку знакомства с Yupland через обучение, задания и игровые режимы.
• Что видно в текущем интерфейсе? Маршрут из 42 модулей, опыт и уровни, задания с наградами и PvP-режимы.
• Что заняло больше всего времени? Работа с Telegram initData: получение, сохранение, обработка разных вариантов кодирования и проверка подписи на сервере.