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