Інтеграція Web3Modal: де обривається підключення
Підключення гаманця в dApp рветься не на кнопці «підключити», а на стику трьох шарів: провайдера всередині гаманця, мережі, до якої він прив’язаний, і стану сесії в інтерфейсі.
Web3Modal закриває шар представлення — вікно вибору провайдера й перемикання мережі — але не прибирає розсинхронізацію між ними. Інтеграція Web3Modal ламається саме там, де шари розходяться.
Найчастіше — невідповідність мережі: гаманець повертає ідентифікатор, якого немає у списку мереж застосунку, і замість пропозиції перемкнутися користувач отримує помилку підключення.
Другий сценарій — мережа у списку є, але не оголошена з параметрами додавання: гаманець відкриває форму ручного введення, і все залежить від того, чи правильно користувач перепише адресу вузла та символ валюти.
Обрив сесії виглядає інакше: вкладка заснула, сторінка перезавантажилася або вузол перестав відповідати — провайдер втратив стан, а інтерфейс продовжує вважати користувача підключеним.
Кнопка знову пропонує підключити гаманець, підпис запитується в порожньої адреси — для користувача це помилка підключення, хоча підключення відбулося.
Окрема точка відмови — різні списки гаманців на різних екранах: у модальному вікні один набір, в особистому кабінеті перевіряється інший, на мобільному підключається третій. Користувач проходить підключення, а система вважає його непідтвердженим.
Розбираємо, як це закривається: єдиний список мереж і провайдерів, відновлення сесії після перезавантаження, перемикання мережі без ручного введення.
Що дає єдиний модуль підключення гаманців
Підключення гаманця — перша дія користувача й перше місце, де він іде. Коли кожен гаманець і кожна мережа обробляються окремою гілкою коду, стан з’єднання розходиться між екранами, а будь-який збій списують на «гаманець не працює».
Єдиний модуль зводить це до одного сценарію: користувач вибирає спосіб входу, усе інше бере на себе інтеграція Web3Modal. Що саме змінюється у вимірюваних величинах:
- Частка невдалих підключень. Відмову на виборі мережі або на підписі оброблено явно: користувач бачить причину й повторює спробу в тому самому вікні, без перезавантаження сторінки. Обриви на вході перестають бути невидимими.
- Час до першого входу. Список гаманців і мереж підвантажується заздалегідь, а не в момент кліку, тому між вибором і підтвердженням немає паузи на ініціалізацію з’єднання.
- Підтримка гаманців. Новий гаманець додається як параметр конфігурації, а не як окремий екран — розширення списку не потребує правок інтерфейсу й нового циклу перевірок.
- Кастомні мережі. Основна мережа й тестовий контур описуються списком параметрів, перемикання між ними не скидає стан підключення й не змушує входити заново.
- Повторні спроби. Модуль сам відстежує зміну акаунта й мережі на боці гаманця та підтягує новий стан — користувачеві не потрібно оновлювати сторінку вручну.
- Звернення до підтримки. Типове «не підключається» замінюється зрозумілим статусом з’єднання й текстом помилки, тому до підтримки надходять реальні збої, а не питання про те, яку кнопку натиснути.
- Спостережуваність. Події підключення, відмови й повторної спроби логуються однаково для всіх гаманців — видно, на якому кроці губляться користувачі.
Ефект перевіряється за трьома числами: частка успішних перших входів, середній час до підпису першої транзакції та кількість звернень за темою підключення. Ці самі метрики стають точкою відліку для наступних змін.
Інтеграція Web3Modal: порівняння трьох підходів
Спосіб підключення гаманця визначає, з якими гаманцями, мережами й платформами dApp сумісний на старті та що доведеться дописувати після. Інтеграція Web3Modal — це три різні сценарії: готовий модуль підключення, власна форма входу й зовнішній провайдер єдиного входу.
Сумісність із гаманцями, мобільними браузерами й нетиповою мережею в них різниться, тому критерій вибору — не швидкість першого запуску, а де проходить межа вашої відповідальності.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Готовий модуль підключення | Популярні мережі, потрібне широке охоплення гаманців і мобільний доступ одразу | Нетипову мережу й власний провайдер входу додають поверх; частину оформлення екрана задає сам модуль |
| Власна форма входу | Потрібен контроль над сценарієм, брендований екран, нестандартний список гаманців | Підтримка мобільних гаманців і оновлення списків — на вашому боці, у разі зміни стандартів правите самостійно |
| Зовнішній провайдер входу | Єдиний вхід для співробітників або партнерів поряд із гаманцем | Залежність від доступності посередника, обмежений набір мереж, дані про сесію поза вашим контуром |
На практиці частіше беруть готовий модуль як основу й дописують власну обгортку: реєстр гаманців і мереж залишається під контролем, а типові сценарії не пишуться заново.
Якщо у вході бере участь зовнішній провайдер, заздалегідь перевіряємо, які мережі він підтримує та що відбувається із сесією в разі його недоступності — це найчастіше джерело несумісності під час розвитку dApp.
Етапи впровадження: від аудиту входу до передачі
Інтеграція Web3Modal починається не з коду, а з інвентаризації того, як користувач потрапляє в застосунок зараз. Аудит входу й схема мереж заздалегідь визначають, які гаманці, браузери та ланцюжки мають працювати, — інакше частина підключень відпадає вже після релізу.
- Аудит входу. Збираємо поточні точки входу: розширення, мобільні гаманці, соцвхід, вбудовані браузери. Фіксуємо, де губиться сесія й як зараз зберігається стан підключення.
- Схема мереж. Описуємо основний і резервний вузол мережі, кастомні ланцюжки та поведінку в разі невідповідності мережі очікуваній. Схема узгоджується до налаштування, щоб не переписувати логіку перемикання.
- Налаштування підключення. Формуємо список гаманців і порядок їх показу, поріг перемикання на мобільний сценарій, обробку повторних підключень і паралельних запитів.
- Перевірка підписів. Тестуємо підпис повідомлення: домен, термін дії, звірку адреси, відхилення запиту в гаманці. Підпис обов’язково переперевіряється на сервері — клієнтській перевірці довіряти не можна.
- Перевірка сценаріїв збою. Проганяємо зміну акаунта, відключення мережі, недоступний вузол, скидання кешу й застарілу сесію: на кожному кроці користувач має бачити зрозумілий вихід, а не помилку.
- Передача до підтримки. Віддаємо конфігурації, схему потоків підключення, перелік діагностичних перевірок і пам’ятку першої лінії — за якими ознаками відрізняти збій гаманця, мережі та нашого коду.
Кожен етап закінчується артефактом — схемою, конфігурацією або звітом про прогін, — тому передача не залежить від конкретного інженера.
Конфігурації мереж, політики доступу та документація
Ключове в передачі — не сам працюючий інтерфейс, а набір артефактів, за якими ваша команда зможе змінювати мережі, додавати гаманці й розбирати збої без нас.
Складаємо їх у той самий репозиторій, де живе код: тоді будь-яка правка проходить рев’ю й залишає слід, а не осідає в листуванні. Нижче — мінімальний перелік того, що залишається в замовника.
- Конфігурація мереж — адреси вузлів, ідентифікатори основної мережі й тестових контурів, налаштування користувацької мережі з її оглядачем блоків, символікою та параметрами оплати комісії.
- Реєстр гаманців — таблиця підключених варіантів входу: браузерні розширення, мобільні застосунки, вхід через зовнішнього постачальника облікових записів. За кожним рядком — статус, власник і порядок відключення, щоб виведення провайдера не перетворювалося на розкопки.
- Політики доступу — хто і на якій підставі змінює параметри мережі та список гаманців; для бойового контуру — правило двох погоджувачів і заборона правок напряму в інтерфейсі.
- Схема авторизації — потік від вибору гаманця до прив’язки адреси до профілю: обробка зміни акаунта, зміни мережі, відхиленого підпису й повторного входу.
- Інструкція з додавання мережі — покроковий порядок для нової мережі або власного блокчейну: адреси контрактів, перевірка на тестовому контурі, умови допуску в бойовий.
- Регламент підтримки — що робити в разі масової відмови провайдера, як відкотити конфігурацію до попередньої версії та в які журнали дивитися насамперед.
- Тексти помилок і підказок — готові формулювання для служби підтримки, щоб відповіді не розходилися з поведінкою інтерфейсу.
- Журнал змін — версіонування файлів конфігурації поряд із кодом: будь-яка минула збірка відтворювана, тому відкат займає хвилини.
Передаємо це пакетом із чек-листом приймання: ваші інженери проходять за ним і підтверджують, що кожен пункт перевірено на живому контурі.
Кейс: зниження частки невдалих підключень утричі
Що було до єдиного модуля входу
Вхід збирали під кожен гаманець окремо: власний обробник підключення, власна перевірка мережі, власний вивід помилок. Частина сесій обривалася на етапі згоди — людина підписувала запит, поверталася в браузер і бачила, що підключення немає.
Головна причина — невідповідність мережі: гаманець відкривався в непідтримуваному ланцюжку, і застосунок мовчки відмовляв.
З першої спроби проходив 61% входів, решта — повторні натискання й повторні підписи. Звернення до підтримки за темою «не підключається» займали близько третини всіх і майже кожне потребувало ручного розбору логів.
Що змінили
Вхід перевели на єдиний модуль на Web3Modal: виявлення встановлених гаманців, підключення з мобільних через міст, відновлення сесії після повернення в браузер.
Реєстр мереж описали декларативно — якщо гаманець відкрито не в тому ланцюжку, застосунок пропонує перемкнутися або додати її замість відмови. Помилки розклали за класами: відмова користувача, тайм-аут моста, непідтримувана мережа — у кожного своє повідомлення й наступний крок.
Що стало
З першої спроби підключається 89% (було 61%), частка невдалих підключень скоротилася втричі. Повторні підписи зникли — сесія відновлюється за тим самим ключем.
Звернення до підтримки щодо входу впали з третини до 9%, а розбір більше не потребує логів: клас помилки видно в аналітиці.
Нові мережі та гаманці додаються конфігурацією, без правок коду входу — передбачуваність входу більше не залежить від того, що з’явилося у провайдерів.
Що робити, якщо гаманець уже підключено через власну форму?
Форму можна не зносити: загальний модуль стає єдиною точкою підключення, а попередня форма — тонкою обгорткою над ним. Вона зберігає свій зовнішній вигляд і адресу, але список гаманців, обробку мереж і відновлення зв’язку бере зі спільного шару. Так інтеграція Web3Modal не ламає те, що вже працює в користувачів.
Вже видані сесії не розриваємо. Модуль читає обидві схеми зберігання — попередню й нову — і за першого ж звернення переносить запис в актуальне сховище.
Події зміни акаунта й мережі надходять в одному форматі для обох шляхів, тому логіка екранів і повідомлень залишається зворотно сумісною, і користувачеві не потрібно підключатися заново.
Перехід відбувається без простою: маршрутизація за ознакою сесії, увімкнення частками трафіку й один перемикач для відкату. Якщо на новій гілці випливає помилка, повертаємо потік на попередній шлях, не торкаючись даних людей. Кожен крок проганяємо на копії робочої конфігурації, а не на живому трафіку.
Окремо закриваємо рідкісні випадки: відновлення після перезавантаження сторінки, відключення гаманця ззовні, мережі, яких немає в базовому списку — їх заводять як кастомні через реєстр.
Схему перенесення сесій і перелік перевірок фіксуємо в чек-листі, щоб міграцію можна було повторити на будь-якому середовищі.
На виході старі користувачі не помічають зміни, нові потрапляють у єдиний контур, а точка правок залишається одна.
Технічні сумніви: мережі, підписи, відновлення доступу
Разові підключення зазвичай працюють з першого разу й створюють хибне відчуття готовності. Основна частина збоїв проявляється пізніше: користувач повертається через тиждень, змінює мережу, оновлює гаманець — і підпис перестає проходити. Нижче — розбір технічних сумнівів, які найчастіше випливають на прийманні.
Ми виходимо з того, що підключення — це стан, а не одноразова дія: вибір провайдера, звірка мережі, підпис, термін життя сесії та коректний вихід мають бути описані явно.
Гаманець підключається до нетипової мережі, якої немає у списку — що робити?
Мережа описується параметрами (ідентифікатор, адреси вузлів, оглядач) і додається запитом до гаманця. Відмова користувача — штатний сценарій: показуємо інструкцію, а не помилку.
Після перемикання звіряємо фактичний ідентифікатор мережі з очікуваним, інакше транзакція піде не туди.
Чому підпис не проходить, хоча гаманець підключено?
Помилка підпису майже завжди означає розходження контексту: гаманець перевіряє, що підписуваний текст відповідає поточній адресі ресурсу та ланцюга.
Тому повідомлення збирається на сервері, включає одноразовий код і термін життя, а перевірка підпису відбувається на бекенді — результату на клієнті не довіряємо.
Що із сесією під час оновлення сторінки або недоступності єдиного входу?
Вхід і гаманці живуть як незалежні способи входу, зведені до однієї сесії на нашому боці. Токен обмежений за терміном і прив’язаний до пристрою, його можна відкликати.
Якщо зовнішній провайдер недоступний, користувач входить гаманцем, а стан підключення відновлюється без повторного проходження.
Гаманець оновився й змінив поведінку — інтеграція зламається?
Список гаманців і адаптери тримаємо в конфігурації, а не в коді: заміна запису не потребує перескладання логіки. Регресійні перевірки покривають ланцюжки підключення, зміни мережі й підпису, тому несумісність після оновлення Web3Modal виявляється до релізу, а не в підтримці.
Обговоримо задачу: склад робіт і план впровадження
Щоб повернутися з оцінкою термінів, а не із загальними словами, потрібні вхідні дані: перелік мереж і гаманців, які мають працювати, поточне підключення та вимоги до авторизації.
Опишіть задачу — цього достатньо, щоб зібрати склад робіт і показати план впровадження за етапами, з перевіркою на кожному.
- Сценарії входу: підключення гаманця, єдиний вхід (SSO), прив’язка адреси до акаунта користувача.
- Цільові мережі: основна, тестові та користувацькі, якщо мережу потрібно додавати прямо з інтерфейсу.
- Поточна реалізація: що вже працює та на яких пристроях ламається підключення.
- Доступи: репозиторій, тестовий стенд, права на збірку й розміщення.
- Інтерфейс: макети вікна підключення, стани завантаження, помилки, поведінка на мобільних.
- Обмеження: браузери, вбудовані гаманці, корпоративні політики доступу.
- Аналітика: події щодо підключення, які потрібно відстежувати для звітності.
Результат передаємо за кроками: робочий стенд, конфігурації мереж, документація з підключення та інструкція для підтримки. Після передачі ваша команда зможе додавати нові мережі та способи входу самостійно, без звернення до нас.
Оцінку термінів даємо після розбору вхідних даних — разом із нею надходить план впровадження та порядок передачі.







