Web3Modal в dApp: подключение кошельков, SSO и кастомные сети

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

Web3Modal в dApp: подключение кошельков, SSO и кастомные сети

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

Интеграция Web3Modal: где отваливается подключение

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

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

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

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

Что даёт единый модуль подключения кошельков

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

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

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

Интеграция Web3Modal: сравнение трёх подходов

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

Вариант Когда подходит Ограничения
Готовый модуль подключения Популярные сети, нужен широкий охват кошельков и мобильный доступ сразу Нетиповую сеть и свой провайдер входа добавляют поверх; часть оформления экрана задаёт сам модуль
Своя форма входа Нужен контроль над сценарием, брендированный экран, нестандартный список кошельков Поддержка мобильных кошельков и обновление списков — на вашей стороне, при смене стандартов правите сами
Внешний провайдер входа Единый вход для сотрудников или партнёров рядом с кошельком Зависимость от доступности посредника, ограниченный набор сетей, данные о сессии вне вашего контура

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

Этапы внедрения: от аудита входа до передачи

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

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

Каждый этап заканчивается артефактом — схемой, конфигурацией или отчётом о прогоне, — поэтому передача не зависит от конкретного инженера.

Конфигурации сетей, политики доступа и документация

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

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

Передаём это пакетом с чек-листом приёмки: ваши инженеры проходят по нему и подтверждают, что каждый пункт проверен на живом контуре.

Кейс: снижение доли неудачных подключений втрое

Что было до единого модуля входа

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

С первой попытки проходил 61% входов, остальное — повторные нажатия и повторные подписи. Обращения в поддержку по теме «не подключается» занимали около трети всех и почти каждое требовало ручного разбора логов.

Что изменили

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

Что стало

С первой попытки подключается 89% (было 61%), доля неудачных подключений сократилась втрое. Повторные подписи ушли — сессия восстанавливается по тому же ключу. Обращения в поддержку по входу упали с трети до 9%, а разбор больше не требует логов: класс ошибки виден в аналитике.

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

Что делать, если кошелёк уже подключён через свою форму?

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

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

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

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

На выходе старые пользователи не замечают смены, новые попадают в единый контур, а точка правок остаётся одна.

Технические сомнения: сети, подписи, восстановление доступа

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

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

Кошелёк подключается к нетиповой сети, которой нет в списке — что делать?

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

Почему подпись не проходит, хотя кошелёк подключён?

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

Что с сессией при обновлении страницы или недоступности единого входа?

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

Кошелёк обновился и сменил поведение — интеграция сломается?

Список кошельков и адаптеры держим в конфигурации, а не в коде: замена записи не требует пересборки логики. Регрессионные проверки покрывают цепочки подключения, смены сети и подписи, поэтому несовместимость после обновления Web3Modal выявляется до релиза, а не в поддержке.

Обсудим задачу: состав работ и план внедрения

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

  • Сценарии входа: подключение кошелька, единый вход (SSO), привязка адреса к аккаунту пользователя.
  • Целевые сети: основная, тестовые и пользовательские, если сеть нужно добавлять прямо из интерфейса.
  • Текущая реализация: что уже работает и на каких устройствах ломается подключение.
  • Доступы: репозиторий, тестовый стенд, права на сборку и размещение.
  • Интерфейс: макеты окна подключения, состояния загрузки, ошибки, поведение на мобильных.
  • Ограничения: браузеры, встроенные кошельки, корпоративные политики доступа.
  • Аналитика: события по подключению, которые нужно отслеживать для отчётности.

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

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

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

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