Кошелёк не подключается: где ломается интеграция WalletConnect
Подключение мобильного кошелька — самый хрупкий участок сценария. На десктопе сессия живёт, пока открыта вкладка, а на телефоне пользователь уходит в кошелёк и возвращается — и на этом переходе рвётся то, что казалось рабочим.
Первая точка отказа — разрыв сессии при переключении между приложениями. Операционная система выгружает фон, соединение с ретранслятором теряет активность, а при возврате приложение считает канал живым и продолжает ждать ответа, которого уже не будет.
Вторая — сканирование кода подключения. Если код открыт во внешнем сканере, возврат идёт не в приложение, а на главный экран кошелька; повторная попытка создаёт вторую пару ключей, и пользователь видит ошибку подключения кошелька при формально активной сессии.
Третья — потеря ответа на запрос подписи: транзакция уже подписана и отправлена, но ответ не дошёл до приложения, и оно показывает отказ там, где операция прошла. Четвёртая — несовпадение сети: кошелёк работает в другой сети, подпись собирается для чужого идентификатора, и подтверждение молча зависает.
Все четыре сбоя лежат не в логике продукта, а на границе между приложением и кошельком. Разбираем, как каждая из них закрывается на уровне интеграции WalletConnect.
Что даёт бесшовное подключение кошельков в приложении
Каждый лишний шаг между намерением подписать и подписью стоит конверсии подключений. Типовой сбой: пользователь уходит в приложение кошелька, возвращается — сессия не восстановлена, и он снова видит кнопку «Подключить». Часть аудитории на этом останавливается, и до запроса подписи дело не доходит.
Мы делаем подключение на WalletConnect с постоянной сессией: ключи и идентификатор сохраняются на устройстве, поэтому возврат из кошелька проходит без повторного рукопожатия, а смена сети не рвёт связь, а подтягивает актуальный идентификатор цепи. Ветка «ушёл и не вернулся» закрывается ожиданием подтверждения с ограничением по времени и явным статусом на экране.
Время повторного входа сокращается до одного подтверждения — сессия с продлением срока жизни переживает закрытие вкладки и перезапуск приложения. Вместо четырёх-пяти шагов при каждом заходе остаётся один экран, а доля дошедших до подписи растёт в разы относительно сценария со сканированием кода на входе.
Доля успешных подписей держится на предварительных проверках: перед запросом приложение сверяет адрес, сеть и наличие средств на комиссию, поэтому ошибка не всплывает уже после подтверждения. Класс отказов «подписал, но транзакция не ушла» почти исчезает, и повторные попытки не съедают время пользователя.
Для поддержки это прямые метрики: обращения «кошелёк не подключается» и «транзакция зависла» перестают быть массовыми, остаётся узкий поток вопросов по отдельным кошелькам. Удержание растёт следом — пользователь, один раз прошедший путь без трения, возвращается в приложение, а не ищет альтернативу.
Способы подключения кошелька: сравнение вариантов
Варианты подключения кошелька различаются тем, где хранится ключ и кто подписывает транзакцию — от этого зависит охват устройств и число точек отказа. Ограничения мобильных браузеров ломают любой сценарий, рассчитанный только на вставленный в страницу провайдер: расширений там нет, фоновая вкладка засыпает, а возврат из приложения по ссылке сбрасывает контекст.
Интеграция WalletConnect закрывает мобильный сценарий через посредника подключения, но не отменяет остальные способы. Ниже — сравнение способов подключения, которые мы обычно собираем в одном приложении.
| Вариант | Когда подходит | Ограничения |
|---|---|---|
| Прямой обмен с кошельком | Настольный браузер с расширением, подпись в один клик | В мобильных браузерах недоступен; ключ остаётся внутри кошелька |
| Посредник-передатчик (релей) | Мобильный кошелёк и настольный браузер через QR-код, единый сценарий | Нужен устойчивый канал, отдельный слой сессий и корректный отзыв доступов |
| Встроенный шлюз | Быстрый вход без установки расширения, простые сценарии | Ключ хранит провайдер — часть пользователей отказывается от такого входа |
| Только настольный браузер | Внутренние панели и административные сценарии | Отрезает мобильный трафик, а на нём основная доля новых подключений |
На практике посредник подключения становится основным путём для мобильных, прямой обмен — быстрым путём для настольных браузеров, а встроенный шлюз остаётся запасным. Такой набор покрывает почти весь трафик подключений: отказ одного способа не блокирует вход остальным.
Интеграция WalletConnect в приложение: этапы работ
Подключение мобильного кошелька почти никогда не отваливается на прямом сценарии: пользователь сканирует код, подтверждает доступ — и всё работает. Ломается оно на возвратах: приложение ушло в фон, устройство сменило сеть, сессия истекла, кошелёк обновился и перестал отвечать на прежний формат запроса. Поэтому работа идёт этапами — от разбора текущей схемы подключения до регламента сопровождения, где зафиксировано, кто и как реагирует на такие изменения.
- Разбор текущей схемы. Смотрим, какие кошельки и сети уже поддержаны, где хранится состояние сессии, какие сбои приходят от пользователей и поддержки, что мешает добавить новые кошельки без переписывания логики.
- Проектирование сессий. Фиксируем срок жизни сессии, правила её восстановления после перезапуска приложения, порядок отзыва доступа и поведение при нескольких активных сессиях на одном аккаунте.
- Сборка подключения. Десктоп получает код для сканирования, мобильный — переход в приложение кошелька и корректный возврат обратно, с сохранением контекста операции, которую пользователь начинал.
- Обработка отказов. Отдельно прорабатываем таймауты, повторные попытки, отказ пользователя от подписи и обрыв связи в момент подтверждения — чтобы транзакция не терялась молча.
- Проверка на реальных устройствах. Гоняем сценарии на матрице: разные версии системы, встроенные браузеры кошельков, планшеты, медленная сеть. Эмулятор здесь не показатель.
- Передача. Отдаём схему подключения, конфигурации окружений, описание точек отказа и инструкцию для первой линии поддержки.
- Регламент сопровождения. Определяем, как отслеживаем изменения на стороне кошельков, кто обновляет конфигурацию и за какое время восстанавливаем работу.
Конфигурация, схемы и регламенты: что передаём по итогам работ
Итог работ — не только подключённый кошелёк внутри приложения, но и комплект, по которому ваша команда сможет сама менять настройки, добавлять сети и разбирать обращения поддержки без нас. Всё складываем в один набор и на приёмке проходим по нему вместе с вашими инженерами — от конфигурации до действий дежурного.
Что остаётся у вас на руках:
- Конфигурация окружений — наборы настроек для тестового и промышленного контуров: идентификатор проекта, разрешённые сети и источники, список переменных и порядок добавления нового окружения.
- Схема потоков подключения — путь от инициации сессии до подписи транзакции, включая возврат пользователя из приложения кошелька, восстановление сессии после перезапуска и обработку отказа.
- Политики доступа — где хранятся ключи, кому выдаются, как проходит ротация и как разделены права между разработкой, поддержкой и инфраструктурой.
- Передаваемая документация — описание модуля, перечень поддерживаемых кошельков и сетей, известные ограничения и журнал изменений по релизам.
- Инструкция для поддержки — типовые обращения (сессия не восстанавливается, транзакция отклонена, кошелёк не открывается) и что делать на каждом шаге.
- Схема диагностики — какие события пишем в журнал и как отличить сбой на нашей стороне от отказа на стороне кошелька.
- Регламент обновлений — как отслеживаем изменения протокола, что делаем при несовместимости версий и в каком порядке откатываемся.
Кейс: подключение кошельков в сервисе с ростом активных пользователей
Сервис с растущей аудиторией подключал мобильные кошельки через самописный мост: QR-код, ручной опрос состояния и своя логика восстановления сессии. Пока пользователей было немного, схема держалась, но с ростом нагрузки начала рассыпаться — сессия терялась при сворачивании приложения, а на части устройств подпись вообще не доходила до кошелька.
Замеры до переезда выглядели так: доля неудачных подключений — 34%, время до первой подписи — от 90 секунд и выше, в среднем 2.4 повторные попытки на пользователя. Поддержка тонула в однотипных обращениях «кошелёк не видит приложение».
Что изменили
Мы перевели транспорт и жизненный цикл сессий на актуальную ветку WalletConnect. Соединение поднимается через промежуточные узлы, ключи сессии живут на стороне клиента, а разрыв после сворачивания приложения восстанавливается сам — без повторного сканирования QR. Переход по ссылке из браузера и QR-код ведут в один и тот же сценарий, поэтому логика не раздваивается между платформами.
Что показали метрики
Доля неудачных подключений упала с 34% до 6% — остаток это отказы самих пользователей и несовместимые сборки кошельков. Время до первой подписи сократилось до 20-25 секунд, повторные попытки — до 1.05 на пользователя, то есть сценарий проходит с первого раза. Обращений в поддержку по теме подключения стало меньше почти в семь раз, а доля мобильных подключений выросла: отпал шаг со сканированием QR на том же устройстве, где открыт сервис.
Чем отличается встроенный шлюз от внешнего кошелька и что выбрать
Разница между встроенным шлюзом и внешним кошельком сводится к одному: где лежит приватный ключ и кто отвечает за его сохранность. Встроенный шлюз держит ключи на стороне приложения — пользователь входит привычным способом, а подпись операции формируется внутри сервиса. Внешний кошелёк оставляет ключ у пользователя: приложение получает адрес и готовую подпись, но не касается самого секрета.
Из этого вырастает разница в охвате аудитории. Встроенный вариант снижает порог входа и работает у любого, кто открыл сервис с телефона, включая тех, у кого кошелька ещё нет. Внешний подключает только владельцев кошельков, зато приносит аудиторию, которая уже привыкла подписывать операции и внимательно проверяет запрашиваемые доступы. Протокол вроде WalletConnect решает как раз вторую задачу — связывает мобильный кошелёк с интерфейсом без переноса ключа.
Проигрывают оба варианта в своих сценариях. Встроенный шлюз не подходит там, где речь о крупных суммах и долгом хранении активов: пользователь не отдаст ключ сервису, а вы получаете на себе всю ответственность за его утечку. Внешний проигрывает в массовых коротких операциях — часть пришедших просто не дойдёт до подписи, потеряв интерес на установке кошелька.
Выбор варианта подключения делают от основной задачи. Если активы хранятся долго, а ставки высоки, единственным путём оставляют внешний кошелёк. Если важны массовость и быстрый первый вход, основным становится встроенный шлюз. На практике чаще собирают оба: внешний как основной путь, встроенный — как запасной для тех, кто пришёл без кошелька, с явным ограничением по объёму операций.
Технические сомнения: сессии, ключи, восстановление
Сессия сопряжения держится на симметричном ключе, который создаётся на устройстве пользователя, а приватные ключи кошелька не покидают само приложение-кошелёк. Мы получаем из сессии только адрес, подписи и согласованный набор методов и сетей — права фиксируются в момент подтверждения и расширению со стороны приложения не подлежат.
Обрыв связи или перезапуск кошелька сессию не убивают: идентификатор и ключ хранятся локально, клиент переподключается к той же паре и досылает пропущенные запросы. Живёт сессия ограниченное время, поэтому в сценарий закладываем повторное сопряжение и проверку состояния перед отправкой транзакции.
Ключи кошелька проходят через вашу серверную часть?
Нет. Подпись формируется внутри кошелька, наружу уходит только её результат и адрес. У нас хранится состояние сессии и история запросов, но не секреты — компрометация серверной части не даёт доступа к средствам.
Что происходит с запросом при обрыве связи?
Он встаёт в очередь и повторяется с нарастающей паузой, поэтому кратковременная потеря сети не превращается в потерянную транзакцию. Если кошелёк закрыт, запрос ждёт возврата пользователя; после истечения сессии предлагаем отсканировать код заново.
Работает ли это со старыми сборками кошельков?
Актуальная ветка протокола поддерживается большинством современных кошельков, но не всеми. На старте сверяем список из вашей аудитории и для неподдерживаемых оставляем запасной путь — подключение по коду или через расширение в браузере, с тем же набором подписываемых операций.
Обсудим задачу: подберём схему подключения под ваш продукт
Чтобы вернуться с оценкой и планом работ, а не с общими формулировками, нам нужно понимать ваш ландшафт: где живёт приложение, какие кошельки уже в ходу у аудитории и что именно ломается в текущем подключении. Ниже — то, что полезно подготовить к разговору; часть пунктов обычно проясняется прямо в переписке.
- Платформы и их ограничения: веб, мобильное приложение, встроенный браузер — от этого зависит, идём через QR-код, deep link или нативное сопряжение.
- Сценарии: только подключение и подпись транзакций или ещё чтение адреса, смена сети, отзыв сессии и повторное подключение без нового сканирования.
- Целевые сети: одна цепочка или несколько, нужны ли переключения между ними внутри одной сессии.
- Текущая схема: набор поддерживаемых кошельков, где хранится состояние сессии и что происходит при сворачивании приложения.
- Ограничения: требования к хранению ключей, политика по внешним сервисам, сроки внедрения и ближайшие релизы.
- Точки отказа: что пишут в поддержку чаще всего — отвал сессии, зависший запрос, расхождение сети.
Опишите задачу в свободной форме: этого хватит, чтобы мы вернулись с оценкой и планом — этапами работ, подбором схемы подключения под ваши платформы и тем, что потребуется с вашей стороны. WalletConnect берём как основу, но конкретную схему выбираем под продукт, а не наоборот.







