Інтеграція TON Connect: dApp і Telegram Mini App

Чому підключення через TON Connect зривається в бойових умовах

Сценарій підключення гаманця виглядає лінійним лише на схемі.

У бойових умовах помилки TON Connect починаються там, де до справи долучається реальний користувач: недоступний провайдер, інша версія клієнта, розрив за часом очікування — і замість підпису транзакції людина бачить порожній екран або нескінченний індикатор завантаження.

Найчастіша причина — втрата стану під час повернення в додаток. Користувач переходить у гаманець, підтверджує підключення, повертається — а додаток уже не пам’ятає, яку сесію ініціював.

Ідентифікатор сесії скинуто, вхідне посилання не зіставлено з початковим запитом, і замість продовження сценарію ми отримуємо повторне коло підключення.

Далі — несумісність версій гаманця. Різні збірки по-різному повертають підтвердження, частину методів просто не підтримують, а обробник тлумачить мовчання як відмову.

На етапі підтвердження транзакції це виглядає як зрив: гаманець відкрився, людина натиснула «Підтвердити», додаток не дочекався відповіді й скинув сесію разом з уже введеними даними.

Є й третій шар — збій сесії гаманця на боці самого користувача: зміна пристрою, кілька встановлених гаманців, перехід за посиланням із месенджера, де вбудований браузер обрізає повернення в додаток. Усі ці випадки виглядають як «кнопка не працює», хоча ламається конкретний перехід стану.

Ціна такого збою — не дрібна незручність, а втрачений обіг: людина не доводить до кінця ні оплату, ні випуск, ні вхід у сервіс, і вдруге вже не повертається. Нижче розбираємо, як це закривається — від стійкої сесії до коректного відкату під час обриву.

Що дає стабільна інтеграція гаманця

Підключення гаманця — перший крок, на якому втрачається найбільше користувачів: перехід у гаманець і назад, різні гаманці з різною поведінкою, розірвана сесія під час згортання Mini App.

У сценарії без опрацювання цих гілок частка успішних підключень тримається на рівні двох третин, а решта не доходять до першої дії.

Інтеграція будується на TON Connect: єдиний протокол підключення й підпису транзакцій замість саморобних обв’язок під кожен гаманець.

Повернення з гаманця обробляємо окремо — додаток відновлює сесію за збереженим ідентифікатором запиту, тому користувач потрапляє туди ж, де почав, а не на порожній екран.

Що це змінює у вимірюваних величинах:

• частка успішних підключень — 93–97% проти 60–70% до доопрацювання сценарію;
• час до першої дії — 15–20 секунд замість повторних спроб «підключитися ще раз»;
• сесія гаманця переживає згортання Mini App, перехід у гаманець і зміну мережі;
• повернення користувача в додаток не вимагає підключатися заново.

Клас відмов, який тут усувається, — найдорожчий у підтримці: обрив під час повернення, застарілий запит, повторний підпис під час уже надісланої транзакції. Стабільність сесії гаманця закриває ці гілки, і сценарій підключення перестає бути вузьким місцем воронки.

Способи підключення гаманця: порівняння режимів

TON Connect дає єдиний шар підключення гаманця: додаток не отримує приватний ключ, а працює із підписаними запитами.

Але порівняння режимів інтеграції показує, що спосіб підключення задає межі сценарію — де користувач підтверджує операцію, як повертається в інтерфейс і що відбувається, якщо міні-додаток уже відкрито у фоні.

Обмеження способу підключення проявляються не в момент з’єднання, а під час відкату: користувач закрив гаманець, скасував підпис або повернувся в іншій вкладці.

Тому в інтеграції заздалегідь описуємо стан сесії, повтор запиту й екран очікування — інакше підтримка отримує потік звернень «кнопка не спрацювала».

Як проходить інтеграція: етапи інженерної роботи

Інтеграція починається не з коду, а з розбору того, як додаток уже отримує адресу гаманця й підпис користувача. Якщо цей шлях не описано, кожен новий гаманець перетворюється на окрему гілку логіки, а наступна правка ламає попередню. Тому перші два етапи — фіксація поточного стану й схема потоків підключення.

1. Аудит точки входу — розбираємо, де додаток ініціює підключення, як зберігає стан сесії та що залишається від неї після перезавантаження сторінки або повернення з гаманця.
2. Схема потоків підключення — на діаграмі фіксуємо всі гілки: підключення, підпис транзакції, відмова користувача, відключення, повторний вхід.
3. Налаштування середовищ — окремі конфігурації для розробки, тестового контуру й продакшену: адреса маніфесту, домени, перелік підтримуваних гаманців.
4. Реалізація підключення — спільний шар для dApp і Telegram Mini App, щоб стан читався однаково й не дублювався у двох місцях.
5. Перевірка на пристроях — прогін на реальних телефонах і десктопних браузерах із кількома гаманцями, включно з перериванням підпису й повторним входом.
6. Пограничні сценарії — втрата зв’язку, застаріла сесія, зміна гаманця; фіксуємо поведінку й зрозумілі повідомлення для користувача.
7. Передача в супровід — документація щодо потоків, список середовищ і точок відмови, доступи й порядок відкату на попередню конфігурацію.

Конфігурації, ключі та документація після впровадження

Після запуску в проєкті залишається комплект артефактів, за яким команда розвиває підключення TON Connect без автора робіт.

Нижче — що саме передаємо і в якому вигляді, щоб зміна середовищ, оновлення гаманців і розбір інцидентів не перетворювалися на листування із питаннями «як це було зібрано».

• Конфігурації середовищ — тестовий, передпродуктивний і робочий набори параметрів підключення, окремі маніфести під кожен домен, секрети винесено з репозиторію в сховище.
• Схема потоків підключення — від відкриття гаманця й запиту підпису до повернення в додаток, із зазначенням, де формується транзакція, а де перевіряється відповідь.
• Регламент ротації ключів — періодичність зміни, хто ініціює, як перевіряється, що активні сесії в користувачів не відвалюються.
• Політика доступу — ролі у сховищі секретів, порядок видачі й відкликання прав, дії під час звільнення співробітника, журнал звернень до ключів.
• Інструкція для команди — сценарії на часті випадки: підключити новий гаманець, оновити маніфест, відтворити збій на стенді, відрізнити помилку підпису від мережевої.
• План відкату змін — попередня стабільна версія підключення, перелік оборотних і необоротних змін, порядок підтвердження відкату.
• Точки контролю — метрики успішних підключень і журнали відмов, за якими видно деградацію раніше, ніж почнуться звернення користувачів.

Кейс: як зросли успішні підключення гаманця

Замовник прийшов із уже працюючим міні-додатком Telegram: підключення гаманця через TON Connect було реалізовано, транзакції проходили, але до підтвердження доходило менше половини розпочатих сценаріїв.

Завдання формулювалося як «скоротити відвал», тому ми почали не з правок оформлення, а з вимірювання кожного кроку — від натискання кнопки до підпису.

Де втрачалися підключення

Втрати розподілилися не так, як очікувалося. Близько чверті користувачів закривали вікно вибору гаманця й не поверталися — саме перемикання між додатками на телефоні виявилося бар’єром.

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

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

Що змінили й що вийшло

Ми переробили сценарій повністю: стан підключення зберігається до моменту підпису, повторна спроба відновлюється з останнього кроку, а повернення з гаманця автоматично підтягує результат запиту.

Окремо додали розрізнювані стани екрана — очікування, підтвердження, помилка з причиною, — щоб користувач не гадав, що сталося.

На повторних вимірюваннях частка успішних підключень зросла з 41% до 79% від розпочатих сценаріїв. Повторні спроби почали давати результат у двох випадках із трьох замість поодиноких, а час від старту до підпису скоротився майже вдвічі — відпав цикл «закрив і зайшов заново».

Чим відрізняється TON Connect у міні-додатку та на сайті?

У міні-додатку Telegram підключення ініціює вбудований гаманець: користувач залишається в тому ж вікні, зовнішні додатки не відкриваються.

На сайті браузер показує вікно TON Connect: на мобільному гаманець вибирають за QR-кодом із переходом у додаток, на десктопі — через розширення. Звідси розходяться доступні гаманці, точка повернення й спосіб зберігання стану.

Повернення користувача — найболючіше місце. У міні-додатку підтвердження відбувається всередині клієнта, і додаток працює в тому ж контексті.

На сайті мобільний сценарій веде людину в гаманець, а назад повертає посилання: якщо стан не відновлено під час відкриття, вона бачить «не підключено» й повторює вхід. Тому адресу й ознаку підключення зберігають у браузері та звіряють під час кожного завантаження.

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

Зовнішніх гаманців на сайті більше, у кожного свої тайм-аути й спосіб повідомити про зміну мережі, тому шар підключення роблять спільним.

Часті технічні сумніви перед стартом

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

Чи доведеться переписувати готовий код?

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

Як перевірити все до викладки?

Проганяємо сценарії в тестовій мережі: підключення, відхилення підпису, повторне підключення, зміну акаунта, втрату зв’язку в момент надсилання. Окремо перевіряємо повернення з оплати — додаток має коректно розрізняти успіх, скасування й завислу операцію.

Що буде з наявними сесіями під час оновлення?

Сесія зберігається на боці додатка й гаманця, а не всередині конкретної збірки, тому оновлення не змушує користувачів підключатися заново. Якщо формат сесії змінюється, переносимо дані так, щоб старі підключення продовжили працювати.

Обговоримо задачу: що уточнити до старту робіт

Щоб повернутися з оцінкою обсягу робіт, а не із загальними обіцянками, нам потрібні вхідні дані щодо проєкту.

Інтеграція TON Connect рідко зводиться до однієї кнопки «Підключити гаманець»: за нею стоять сценарії підпису, строк життя сесії, обробка відмов і зв’язка гаманця з обліковим записом на вашому боці. Чим точніше постановка задачі на вході, тим менше припущень у плані впровадження.

Що уточнюємо на першій розмові:

• Середовище виконання. Веб-додаток у браузері, міні-додаток усередині Telegram або настільний клієнт — від цього залежить набір підтримуваних гаманців і спосіб обміну даними між вікнами.
• Сценарії використання. Лише вхід за підписом або ще перекази й оплата всередині додатка — кожен сценарій додає свою гілку перевірок і тестів.
• Модель сесії. Строк життя підключення, прив’язка гаманця до профілю, повторний вхід і відкликання доступу під час зміни акаунта.
• Мережа та підтвердження. Працюємо в основній або тестовій мережі, скільки підтверджень чекаємо, як реагуємо на відхилену операцію.
• Що вже є. Поточний код, серверні інтерфейси, схема зберігання користувачів — від цього залежить, пишемо інтеграцію з нуля чи вбудовуємо в готовий контур.
• Навантаження й доступи. Скільки одночасних підключень очікується, які ключі та дані залишаються всередині вашої інфраструктури.
• Критерій готовності. Що вважаємо результатом: саме підключення гаманця чи повний цикл операцій із ним.

За цими відповідями збираємо план впровадження з етапами, склад команди й точки приймання. Опишіть задачу — повернемося з оцінкою та планом робіт.