Почему подключение через TON Connect срывается на бою
Сценарий подключения кошелька выглядит линейным только на схеме. В бою TON Connect-ошибки начинаются там, где к делу подключается реальный пользователь: недоступный провайдер, другая версия клиента, разрыв по времени ожидания — и вместо подписи транзакции человек видит пустой экран или бесконечный индикатор загрузки.
Самая частая причина — потеря состояния при возврате в приложение. Пользователь уходит в кошелёк, подтверждает подключение, возвращается — а приложение уже не помнит, какую сессию инициировало. Идентификатор сессии сброшен, входящая ссылка не сопоставлена с исходным запросом, и вместо продолжения сценария мы получаем повторный круг подключения.
Дальше — несовместимость версий кошелька. Разные сборки по-разному отдают подтверждение, часть методов просто не поддерживает, а обработчик трактует молчание как отказ. На этапе подтверждения транзакции это выглядит как отвал: кошелёк открылся, человек нажал «Подтвердить», приложение не дождалось ответа и сбросило сессию вместе с уже введёнными данными.
Есть и третий слой — сбой сессии кошелька на стороне самого пользователя: смена устройства, несколько установленных кошельков, переход по ссылке из мессенджера, где встроенный браузер обрезает возврат в приложение. Все эти случаи выглядят как «кнопка не работает», хотя ломается конкретный переход состояния.
Цена такого сбоя — не мелкое неудобство, а потерянный оборот: человек не доводит до конца ни оплату, ни выпуск, ни вход в сервис, и второй раз уже не возвращается. Ниже разбираем, как это закрывается — от устойчивой сессии до корректного отката при обрыве.
Что даёт стабильная интеграция кошелька
Подключение кошелька — первый шаг, на котором теряется больше всего пользователей: переход в кошелёк и обратно, разные кошельки с разным поведением, разорванная сессия при сворачивании Mini App. В сценарии без проработки этих веток доля успешных подключений держится на уровне двух третей, а остальные не доходят до первого действия.
Интеграция строится на TON Connect: единый протокол подключения и подписи транзакций вместо самодельных обвязок под каждый кошелёк. Возврат из кошелька обрабатываем отдельно — приложение восстанавливает сессию по сохранённому идентификатору запроса, поэтому пользователь попадает туда же, где начал, а не на пустой экран.
Что это меняет в измеримых величинах:
- доля успешных подключений — 93–97% против 60–70% до доработки сценария;
- время до первого действия — 15–20 секунд вместо повторных попыток «подключиться ещё раз»;
- сессия кошелька переживает сворачивание Mini App, переход в кошелёк и смену сети;
- возврат пользователя в приложение не требует подключаться заново.
Класс отказов, который здесь устраняется, — самый дорогой в поддержке: обрыв на возврате, устаревший запрос, повторная подпись при уже отправленной транзакции. Стабильность сессии кошелька закрывает эти ветки, и сценарий подключения перестаёт быть узким местом воронки.
Способы подключения кошелька: сравнение режимов
TON Connect даёт единый слой подключения кошелька: приложение не получает приватный ключ, а работает с подписанными запросами. Но сравнение режимов интеграции показывает, что способ подключения задаёт границы сценария — где пользователь подтверждает операцию, как возвращается в интерфейс и что происходит, если мини-приложение уже открыто в фоне.
| Вариант | Когда подходит | Ограничения |
|---|---|---|
| Встроенный браузер мини-приложения | Подключение кошелька в мини-приложении: пользователь не покидает Telegram, подпись подтверждается рядом с интерфейсом | Доступен только набор кошельков, поддерживающих работу внутри мини-приложения |
| Внешний кошелёк в отдельном приложении | Нужен максимальный охват кошельков и подтверждение на устройстве пользователя | Требуется возврат в приложение после подписи; на части платформ переход остаётся ручным |
| Подключение на сайте | Настольный и мобильный веб, где Telegram в сценарии не участвует | Свой выбор кошелька, своя обработка разрыва соединения и повторного открытия страницы |
Ограничения способа подключения проявляются не в момент соединения, а на откате: пользователь закрыл кошелёк, отменил подпись или вернулся в другой вкладке. Поэтому в интеграции заранее описываем состояние сессии, повтор запроса и экран ожидания — иначе поддержка получает поток обращений «кнопка не сработала».
Как проходит интеграция: этапы инженерной работы
Интеграция начинается не с кода, а с разбора того, как приложение уже получает адрес кошелька и подпись пользователя. Если этот путь не описан, каждый новый кошелёк превращается в отдельную ветку логики, а следующая правка ломает предыдущую. Поэтому первые два этапа — фиксация текущего состояния и схема потоков подключения.
- Аудит точки входа — разбираем, где приложение инициирует подключение, как хранит состояние сессии и что остаётся от неё после перезагрузки страницы или возврата из кошелька.
- Схема потоков подключения — на диаграмме фиксируем все ветки: подключение, подпись транзакции, отказ пользователя, отключение, повторный вход.
- Настройка окружений — отдельные конфигурации для разработки, тестового контура и продакшена: адрес манифеста, домены, перечень поддерживаемых кошельков.
- Реализация подключения — общий слой для dApp и Telegram Mini App, чтобы состояние читалось одинаково и не дублировалось в двух местах.
- Проверка на устройствах — прогон на реальных телефонах и десктопных браузерах с несколькими кошельками, включая прерывание подписи и повторный вход.
- Пограничные сценарии — потеря связи, устаревшая сессия, смена кошелька; фиксируем поведение и понятные сообщения для пользователя.
- Передача в сопровождение — документация по потокам, список окружений и точек отказа, доступы и порядок отката на предыдущую конфигурацию.
Конфигурации, ключи и документация после внедрения
После запуска в проекте остаётся комплект артефактов, по которому команда развивает подключение TON Connect без автора работ. Ниже — что именно передаём и в каком виде, чтобы смена окружений, обновление кошельков и разбор инцидентов не превращались в переписку с вопросами «как это было собрано».
- Конфигурации окружений — тестовый, предпродуктивный и рабочий наборы параметров подключения, отдельные манифесты под каждый домен, секреты вынесены из репозитория в хранилище.
- Схема потоков подключения — от открытия кошелька и запроса подписи до возврата в приложение, с указанием, где формируется транзакция, а где проверяется ответ.
- Регламент ротации ключей — периодичность смены, кто инициирует, как проверяется, что активные сессии у пользователей не отваливаются.
- Политика доступа — роли в хранилище секретов, порядок выдачи и отзыва прав, действия при уходе сотрудника, журнал обращений к ключам.
- Инструкция для команды — сценарии на частые случаи: подключить новый кошелёк, обновить манифест, воспроизвести сбой на стенде, отличить ошибку подписи от сетевой.
- План отката изменений — предыдущая стабильная версия подключения, перечень обратимых и необратимых изменений, порядок подтверждения отката.
- Точки контроля — метрики успешных подключений и журналы отказов, по которым видно деградацию раньше, чем пойдут обращения пользователей.
Кейс: как выросли успешные подключения кошелька
Заказчик пришёл с уже работающим мини-приложением Telegram: подключение кошелька через TON Connect было реализовано, транзакции проходили, но до подтверждения доходило меньше половины начатых сценариев. Задача формулировалась как «сократить отвал», поэтому мы начали не с правок оформления, а с замера каждого шага — от нажатия кнопки до подписи.
Где терялись подключения
Потери распределились не так, как ожидалось. Около четверти пользователей закрывали окно выбора кошелька и не возвращались — само переключение между приложениями на телефоне оказалось барьером. Ещё часть терялась на обратном пути: возврат из кошелька не восстанавливал состояние сценария, человек видел пустой экран и считал, что подключение не сработало.
Хуже всего работали повторные попытки. Кнопка вела на первый шаг, прогресс не сохранялся, и каждый новый заход начинался с нуля — вместо роста успешных подключений повторный заход воспроизводил тот же тупик.
Что изменили и что получилось
Мы переработали сценарий целиком: состояние подключения сохраняется до момента подписи, повторная попытка возобновляется с последнего шага, а возврат из кошелька автоматически подтягивает результат запроса. Отдельно добавили различимые состояния экрана — ожидание, подтверждение, ошибка с причиной, — чтобы пользователь не гадал, что произошло.
На повторных замерах доля успешных подключений выросла с 41% до 79% от начатых сценариев. Повторные попытки стали давать результат в двух случаях из трёх вместо единичных, а время от старта до подписи сократилось почти вдвое — отпал цикл «закрыл и зашёл заново».
Чем отличается TON Connect в мини-приложении и на сайте?
В мини-приложении Telegram подключение инициирует встроенный кошелёк: пользователь остаётся в том же окне, внешние приложения не открываются. На сайте браузер показывает окно TON Connect: на мобильном кошелёк выбирают по QR-коду с уходом в приложение, на десктопе — через расширение. Отсюда расходятся доступные кошельки, точка возврата и способ хранения состояния.
| Сценарий | Кошелёк | Возврат пользователя | Состояние |
|---|---|---|---|
| Мини-приложение | встроенный в клиент | мгновенный, окно не закрывается | в рамках сессии, восстанавливать не нужно |
| Сайт, мобильный браузер | внешний по QR-коду | по ссылке из кошелька, вкладку восстанавливают | в хранилище браузера, сверяется при загрузке |
| Сайт, десктоп | расширение | вкладка остаётся открытой | там же, отдельная ветка |
Возврат пользователя — самое болезненное место. В мини-приложении подтверждение идёт внутри клиента, и приложение работает в том же контексте. На сайте мобильный сценарий уводит человека в кошелёк, а обратно возвращает ссылка: если состояние не восстановлено при открытии, он видит «не подключён» и повторяет вход. Поэтому адрес и признак подключения хранят в браузере и сверяют при каждой загрузке.
Объём доработок отличается примерно вдвое. Мини-приложению хватает одной ветки подключения: подпись, отправка, отключение. Сайту нужны две ветки — мобильный кошелёк и десктопное расширение, — плюс обработка возврата по ссылке и отключение при смене аккаунта. Внешних кошельков на сайте больше, у каждого свои таймауты и способ сообщить о смене сети, поэтому слой подключения делают общим.
Частые технические сомнения перед стартом
На этапе оценки всплывает один и тот же набор вопросов: какие сети поддерживаются, придётся ли переписывать готовый код, как проверить интеграцию до выкладки и что станет с уже подключёнными пользователями. Ниже — короткие ответы по каждому пункту.
Какие сети поддерживаются?
Основная и тестовая сети переключаются настройками приложения, а не переписыванием логики. Кошелёк сообщает, к какой сети подключён пользователь, и при расхождении транзакция не подписывается — операция в боевом контуре не пройдёт случайно.
Придётся ли переписывать готовый код?
Подключение кошелька — отдельный слой: он отвечает за подпись и отправку транзакций, а бизнес-логика остаётся прежней. Если свой механизм подключения уже есть, его сохраняем и надстраиваем — рабочие модули переписывать не нужно.
Как проверить всё до выкладки?
Прогоняем сценарии в тестовой сети: подключение, отклонение подписи, повторное подключение, смену аккаунта, потерю связи в момент отправки. Отдельно проверяем возврат с оплаты — приложение должно корректно различать успех, отмену и зависшую операцию.
Что будет с существующими сессиями при обновлении?
Сессия хранится на стороне приложения и кошелька, а не внутри конкретной сборки, поэтому обновление не заставляет пользователей подключаться заново. Если формат сессии меняется, переносим данные так, чтобы старые подключения продолжили работать.
Обсудим задачу: что уточнить до старта работ
Чтобы вернуться с оценкой объёма работ, а не с общими обещаниями, нам нужны вводные по проекту. Интеграция TON Connect редко сводится к одной кнопке «Подключить кошелёк»: за ней стоят сценарии подписи, срок жизни сессии, обработка отказов и связка кошелька с учётной записью на вашей стороне. Чем точнее постановка задачи на входе, тем меньше допущений в плане внедрения.
Что уточняем на первом разговоре:
- Среда исполнения. Веб-приложение в браузере, мини-приложение внутри Telegram или настольный клиент — от этого зависит набор поддерживаемых кошельков и способ обмена данными между окнами.
- Сценарии использования. Только вход по подписи или ещё переводы и оплата внутри приложения — каждый сценарий добавляет свою ветку проверок и тестов.
- Модель сессии. Срок жизни подключения, привязка кошелька к профилю, повторный вход и отзыв доступа при смене аккаунта.
- Сеть и подтверждения. Работаем в основной или тестовой сети, сколько подтверждений ждём, как реагируем на отклонённую операцию.
- Что уже есть. Текущий код, серверные интерфейсы, схема хранения пользователей — от этого зависит, пишем интеграцию с нуля или встраиваем в готовый контур.
- Нагрузка и доступы. Сколько одновременных подключений ожидается, какие ключи и данные остаются внутри вашей инфраструктуры.
- Критерий готовности. Что считаем результатом: само подключение кошелька или полный цикл операций с ним.
По этим ответам собираем план внедрения с этапами, состав команды и точки приёмки. Опишите задачу — вернёмся с оценкой и планом работ.
