Подключение TON-кошелька к dApp: интеграция Tonkeeper через TON Connect

Пользователь бросает оплату на полпути, если кошелёк не подключается с первого раза. Мы разрабатываем подключение Tonkeeper к вашему сервису под ключ: разбираем сценарии, настраиваем подпись и передаём рабочий результат с документацией. Доля неудачных попыток падает кратно.

Подключение TON-кошелька к dApp: интеграция Tonkeeper через TON Connect

Web3 фронтендПростой~2-3 дня
Часто задаваемые вопросы

Интеграция Tonkeeper срывается на подписи транзакции

Пользователь доходит до подтверждения в кошельке — и на этом поток останавливается. Подпись транзакции не проходит: окно кошелька закрывается, кнопка нажата, а приложение продолжает ждать ответ, который уже не придёт. Для человека это выглядит как «ничего не произошло», для бизнеса — как брошенный сценарий на последнем шаге.

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

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

Всё это — про склейку состояний: запрос подписи, сессия и события сети должны сходиться в одной точке, иначе интеграция Tonkeeper разваливается на ровном месте. Разбираем, как это закрывается.

Что меняется после подключения кошелька к сервису

Доля подтверждённых транзакций и повторные входы

После интеграции Tonkeeper через TON Connect подпись проверяется до отправки в сеть, поэтому пользователь не попадает в цикл «подписал — отказ — подписал снова». Доля успешных подтверждений растёт за счёт того, что сервис заранее знает адрес, сеть и баланс и не предлагает действие, которое заведомо не пройдёт. Повторные входы ускоряются: сохранённое соединение даёт одно подтверждение вместо полного рукопожатия заново.

Время подключения нового пользователя

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

Классы отказов, которые перестают доходить до поддержки

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

Режимы подключения кошелька и их технические ограничения

Режим подключения определяет не удобство, а то, где останется приватный ключ и какой канал подтверждения получит пользователь. Все варианты опираются на один стандарт, который поддерживает Tonkeeper, поэтому смена режима не требует переписывать логику приложения — меняется только возврат после подписи.

В браузере на компьютере приложение инициирует сессию, кошелёк подтверждает её и подписывает каждую операцию: ключ не покидает хранилище, приложение получает адрес и подпись. На телефоне мешает ограничение мобильных браузеров — переключение вкладок и возврат рвут сессию, поэтому подтверждение выносят в отдельное окно.

Вариант Когда подходит Ограничения
Кошелёк в браузере на компьютере Основной сценарий веб-приложения Мобильный вход не покрыт
Мобильный браузер Быстрый вход с телефона Переключение вкладок рвёт сессию
Подтверждение в отдельном окне Мобильные браузеры Зависит от корректного возврата по ссылке
Связка двух устройств Вход по QR: показ на компьютере, подпись на телефоне Нужны оба устройства и стабильная сеть
Подпись без внешнего кошелька Тесты, автоматизация, сервисные операции Ключ в приложении — выше требования к хранению

Типовая ошибка — выбирать режим по виду кнопки, а не по тому, где живёт ключ и как пользователь возвращается, — отмечает наш инженер. На телефоне подтверждение в отдельном окне чаще всего ломается на возврате: сессия создана, а результат до приложения не доезжает, и человек считает, что кошелёк не подключился.

Порядок работ: от разбора сценариев до передачи

Порядок внедрения подключения строим так, чтобы каждый шаг опирался на уже проверенный предыдущий. Начинаем не с кода, а с разбора пользовательских сценариев и текущих точек отказа — иначе интеграция Tonkeeper через TON Connect превращается в перебор гипотез на живых людях.

  1. Разбор сценариев пользователя. Что человек делает от входа до подтверждения операции, где возвращается из кошелька, на каком шаге закрывает окно. Точки отказа фиксируем по логам и обращениям поддержки.
  2. Схема взаимодействия с кошельком. Что уходит в кошелёк, что приходит обратно, где хранится состояние сессии и как приложение понимает, что подключение ещё живо.
  3. Настройка подключения и обработки ответов. Ответ привязываем к конкретной операции, а не к последней открытой — иначе повторный вход создаёт дубль действия.
  4. Обработка отказов подписи и повторных попыток. Разводим отказ пользователя, закрытое окно, истёкшую сессию и обрыв сети: у каждого свой текст и своё поведение.
  5. Проверка перед выкаткой. Что именно считаем пройденным — ниже.
  6. Передача и обучение команды. Разбор кода, схема и инструкция по типовым сбоям, чтобы правки не требовали нас.

Проверка перед выкаткой

Гоняем сценарии на реальных кошельках и браузерах, а не только на внутреннем стенде: возврат из приложения, отказ от подписи, повторное подключение, смена аккаунта. Убеждаемся, что повторный запрос не проводит операцию дважды и что сессия корректно закрывается. Выкатка идёт на долю трафика, откат — возврат предыдущей сборки.

Что передаём на руки после интеграции Tonkeeper

Мы отдаём интеграцию не как набор разовых правок, а как комплект, по которому команда может сама менять подключение, разбирать обращения пользователей и проверять релиз без нас. Ниже — что именно остаётся в репозитории и во внутренней базе знаний на момент сдачи.

Артефакты для инженеров

  • Рабочая конфигурация подключения: список поддерживаемых кошельков, параметры сети и адрес приложения — подключение воспроизводится из репозитория, а не из переписки в мессенджере.
  • Документация по подключению кошелька: точки входа, используемые методы, порядок восстановления сессии после перезагрузки страницы и смены устройства.
  • Схема прохождения подписи: от создания запроса до возврата подписанного сообщения, с отмеченными местами, где проверяется адрес кошелька и срок жизни запроса.
  • Правила обработки отказов и повторных попыток: какие ошибки считаются временными, сколько попыток делаем, с каким шагом и в какой момент предлагаем пользователю переподключиться.
  • Журналирование событий подключения в едином формате: идентификатор сессии, кошелёк, этап, результат, код ошибки — разбор обращения занимает минуты, а не день переписки.
  • Чек-лист самостоятельной проверки после изменений: короткая последовательность шагов перед выкаткой, чтобы обновление фронта не ломало сценарий подписи.

Памятка для поддержки

  • Инструкция по типовым обращениям: не видна кнопка подключения, подпись не проходит, сессия слетает после обновления страницы.
  • Таблица «симптом — причина — действие» со ссылкой на нужную запись в журнале, чтобы первую линию можно было закрыть без эскалации.
  • Границы ответственности: что поддержка решает сама, а что сразу уходит инженерам, с готовыми формулировками ответа пользователю.

Кейс: доля неудачных подписей упала с 12% до 2%

Сервис с подтверждением действий пользователя сделал кошелёк Tonkeeper основным способом входа. Подтверждения терялись на ровном месте: человек уходил в кошелёк, возвращался в другой вкладке или с другого устройства, страница успевала обновиться — состояние подписи сбрасывалось, и внешне это выглядело как «нажал и ничего не произошло».

Что изменили

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

Что смотрим До После
Доля неудачных подписей 12% 2%
Причина отказа разбор по журналам вручную видна сразу и однозначно
Повторная попытка вход в сценарий заново с того же экрана
Обращения поддержки каждое разбирается вручную закрываются по коду причины

Доля неудачных подписей упала с 12% до 2%, а разбор обращений перестал занимать инженерное время. «Раньше мы не могли сказать пользователю, что именно произошло, — теперь причина видна в первой строке, и повтор проходит без выхода из сценария», — руководитель направления.

Чем кошелёк в браузере отличается от кошелька в телефоне?

Расширение в браузере и мобильный кошелёк — это два разных жизненного цикла сессии, и один и тот же код интеграции ведёт себя в них по-разному. Расширение живёт в том же контексте, что и страница: соединение открывается и закрывается вместе с вкладкой, а ответ приходит в уже установленный канал. Мобильный Tonkeeper — отдельное приложение, и между страницей и кошельком появляется разрыв, которого в браузере нет.

Критичной разница становится на возврате результата. Расширение отдаёт адрес или подпись прямо в открытую вкладку, и страница просто ждёт. Мобильный сценарий требует ухода со страницы и возврата по ссылке на адрес приложения — здесь вкладку может выгрузить система, а пользователь вернётся позже, чем истечёт таймер ожидания.

Прерывание пользователем тоже выглядит иначе. В расширении отказ на подтверждении — явное событие: страница получает его и переводит состояние в «отклонено». В телефоне пользователь просто закрывает кошелёк, и в приложение не приходит ничего: запрос не отклонён, а повис, и без явной ошибки его легко принять за успешный.

Закрывается это единой схемой подключения: общий интерфейс на подключение, подпись и отправку, статусная модель, где ожидание, подтверждение, отказ и потеря сессии — разные состояния, и восстановление по сохранённому идентификатору запроса. Тогда кошелёк в браузере и на телефоне проходят один путь, а различается только доставка ответа.

Технические сомнения по подключению кошелька

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

Часть пользователей подключена по старой схеме — придётся их разлогинивать?

Нет. Обе схемы живут параллельно: в записи сессии хранится признак версии подключения, и при входе приложение само определяет, каким путём вести пользователя. Переход делаем ленивым — по факту следующего действия, без принудительного разлогина и повторного подтверждения кошелька. Доля успешных подключений в момент перехода не просаживается.

Нужен ли отдельный сервис для проверки подписи?

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

Можно ли держать несколько кошельков одновременно?

Да. Храним список подключённых кошельков с активным по умолчанию, а не один адрес: пользователь с двумя устройствами переключается без повторного подтверждения, статус остальных сохраняется. Работает с Tonkeeper и другими поддерживаемыми кошельками в одном сценарии.

Кто отвечает за обновление, если кошелёк меняет что-то у себя?

Изменения приходят как новая версия протокола подключения, поэтому держим адаптер и следим за анонсами на стороне кошельков. Совместимость проверяем матрицей поддерживаемых версий и прогоняем сценарий подключения на каждой до релиза, а не по жалобам. Если обратная совместимость ломается, обновляем адаптер, а прежний сценарий остаётся рабочим до планового отключения.

Обсудим задачу: подключение кошелька к вашему сервису

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

  • Описание сценария подтверждения: что именно подписывает пользователь, в какой момент и что делает сервис до и после подписи.
  • Поддерживаемые кошельки и устройства: Tonkeeper как основной ориентир, плюс перечень остальных приложений и платформ, где сценарий обязан работать одинаково.
  • Текущие точки отказа: где подключение уже пробовали и что падает — возврат из приложения без ответа, потеря сессии, повторная подпись.
  • Ожидаемое поведение при отказе: остаётся ли пользователь в сервисе, может ли повторить попытку, что видит поддержка на своей стороне.
  • Сроки выкатки: к какой дате нужен рабочий сценарий и есть ли жёсткие зависимости от смежных работ.
  • Ограничения: требования безопасности, доступы к тестовой среде, регламент работы с реальными операциями.

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

Направления блокчейн-разработки

Последние работы

  • Разработка сайта компании B2B ADVANCE
    Разработка сайта компании B2B ADVANCE
    1574
  • Разработка веб-приложения для компании FEEDME
    Разработка веб-приложения для компании FEEDME
    1427
  • Разработка веб-сайта для компании БЕЛФИНГРУПП
    Разработка веб-сайта для компании БЕЛФИНГРУПП
    1105
  • Разработка интернет магазина для компании FURNORO
    Разработка интернет магазина для компании FURNORO
    1421
  • Разработка логотипа компании B2B Advance
    Разработка логотипа компании B2B Advance
    858
  • Разработка веб-приложения для компании Enviok
    Разработка веб-приложения для компании Enviok
    1181