{"canonical_url":"https://engineer.company/uk/notes/solana-mobile-wallet-deeplinks/","content_markdown":"# Як відкрити dApp у мобільних гаманцях Solana\n\n2026-08-10\n\nReact-dApp, побудований на `@solana/wallet-adapter-react`, без проблем\nпід'єднує десктопні гаманці, але на телефоні той самий сценарій ламається:\nгаманець має відкрити dApp у власному вбудованому браузері, а діплінки, які\nмали б це зробити, мовчки не спрацьовують. Backpack відкриває сторінку\n«завантажте застосунок»; Solflare відкриває застосунок, але ніколи —\nсайт; здається, що не працює жоден варіант. Ми розібрали проблему на частини,\nі виявилося, що це чотири окремі проблеми з одним спільним симптомом.\n\n## Чотири проблеми\n\n- **Посилання для Backpack було сформоване неправильно.** Єдиний\n  задокументований формат — `https://backpack.app/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`:\n  універсальне посилання із цільовим URL у шляху та обов'язковим `ref`. Вгаданий\n  варіант із власною схемою, як-от `backpack://ul/v1/browse?url=...`, не\n  збігається з жодним маршрутом, який реєструє застосунок, тож користувач\n  опиняється на сторінці встановлення гаманця.\n- **Solflare теж потребує свого універсального посилання:**\n  `https://solflare.com/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`, а не голої схеми\n  `solflare://`. Гола схема може запустити застосунок, не сказавши йому, що\n  відкрити, — і виходить саме «застосунок відкривається, але вкладку із сайтом\n  доводиться відкривати вручну».\n- **Обидва параметри мають бути закодовані.** `url` — це повна абсолютна адреса\n  dApp, а `ref` — походження (origin) сторінки, з якої надходить запит; кожен проходить через\n  `encodeURIComponent`. Незакодований `?` або `\u0026` у цільовій адресі ламає\n  розбір, і гаманець відкривається на своєму головному екрані замість вкладки\n  браузера.\n- **Спосіб запуску важить не менше за саме посилання.** Універсальні посилання\n  перемикають застосунки лише під час навігації, якій довіряє операційна\n  система, — а вставлені в адресний рядок навмисно нічого не роблять; саме тому\n  цілком коректне посилання під час тестування «не працює».\n\n## Задокументовані формати\n\n- Phantom: `https://phantom.app/ul/browse/\u003curl\u003e?ref=\u003cref\u003e` — тут без\n  `/v1`.\n- Solflare: `https://solflare.com/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`\n- Backpack: `https://backpack.app/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`\n\nОдин шаблон покриває всі три:\n\n```js\nconst WALLET_BROWSE = {\n  phantom: (url, ref) =\u003e\n    `https://phantom.app/ul/browse/${url}?ref=${ref}`,\n  solflare: (url, ref) =\u003e\n    `https://solflare.com/ul/v1/browse/${url}?ref=${ref}`,\n  backpack: (url, ref) =\u003e\n    `https://backpack.app/ul/v1/browse/${url}?ref=${ref}`,\n};\n\nfunction walletBrowseLink(\n  walletName,\n  targetUrl = window.location.href,\n) {\n  const build = WALLET_BROWSE[walletName.toLowerCase()];\n  if (!build) return null;\n  return build(\n    encodeURIComponent(targetUrl),\n    encodeURIComponent(window.location.origin),\n  );\n}\n```\n\n## Як запустити посилання, щоб iOS та Android його прийняли\n\n- **Виводьте справжнє посилання із заздалегідь обчисленою адресою.** Звичайний\n  `\u003ca href={walletBrowseLink('phantom')}\u003e` — найнадійніший спосіб запуску на\n  обох платформах.\n- **Якщо потрібен програмний перехід**, присвоюйте `window.location.href`\n  синхронно всередині обробника натискання — без `await`, без `fetch`, без\n  `setTimeout` перед цим. Після асинхронної роботи контекст жесту вже втрачено,\n  і iOS натомість відкриває вебсайт гаманця. Ніколи не використовуйте\n  `window.open`.\n- **Ніколи не тестуйте, вставляючи посилання в адресний рядок.** Універсальні\n  посилання там навмисно не спрацьовують; тестуйте натисканням на посилання або\n  QR-кодом, відсканованим камерою.\n- **Зважайте на webview месенджерів.** У вбудованому браузері Telegram чи\n  Instagram універсальні посилання часто просто губляться, і натомість\n  завантажується звичайний вебсайт гаманця. Визначення за user-agent — у кращому\n  разі евристика, тож дайте користувачам ще й видимий запасний вихід: «відкрийте\n  в Safari чи Chrome, а тоді під'єднайтеся».\n\n## Ґрунтовніше виправлення на Android\n\nСаморобні діплінки — це історія про iOS. На Android Mobile Wallet Adapter від\nSolana Mobile дає змогу dApp, що працює в мобільному браузері, під'єднатися\nбезпосередньо до встановленого застосунку гаманця, взагалі без обхідного шляху\nчерез вбудований браузер. Свіжі версії `@solana/wallet-adapter-react` реєструють\nмобільний адаптер автоматично, тож оновлення пакетів wallet-adapter може саме\nсобою виправити ситуацію на Android. Цільова архітектура: Mobile Wallet Adapter\nна Android, універсальні browse-посилання на iOS, де Apple не дозволяє нічого\nрівноцінного.\n\n## Перевірка на пристрої\n\n1. Справжній пристрій, встановлений гаманець, посилання відкрито із системного\n   браузера — не з месенджера.\n2. Натисніть посилання на сторінці або відскануйте QR-код; ніколи не\n   вставляйте в адресний рядок.\n3. Переконайтеся, що гаманець відкривається і dApp завантажується у вкладці\n   його вбудованого браузера — саме друга половина і ламається.\n4. Повторіть без встановленого гаманця: універсальне посилання має відкрити\n   вебсайт гаманця як запасний варіант. Якщо ця сторінка з'являється, коли\n   застосунок встановлено, — посилання або спосіб запуску все ще неправильні.\n5. Потім перевірте шлях через месенджер і додайте підказку «відкрийте у\n   браузері», якщо посилання там не спрацьовує.\n\n## Джерела\n\n- [Phantom: діплінки на iOS та Android](https://docs.phantom.com/phantom-deeplinks/deeplinks-ios-and-android)\n- [Solflare: діплінк Browse](https://docs.solflare.com/solflare/technical/deeplinks/other-methods/browse)\n- [Backpack: діплінк Browse](https://docs.backpack.app/deeplinks/other-methods/browse)\n- [Solana Mobile: Mobile Wallet Adapter](https://docs.solanamobile.com/mobile-wallet-adapter/mobile-apps)\n\n\u003chttps://engineer.company/uk/notes/solana-mobile-wallet-deeplinks/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Чому діплінки Phantom, Solflare і Backpack для відкриття dApp не спрацьовують на телефоні: точні формати, правила запуску й виправлення, з якими вони працюють.","formats":{"gemtext":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/index.gmi","gopher":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/gophermap","html":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/","json":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/index.json","markdown":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/index.md","pdf":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/index.pdf"},"kind":"page","language":"uk","title":"Як відкрити dApp у мобільних гаманцях Solana","url":"https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/","version":1}