# Як відкрити dApp у мобільних гаманцях Solana

2026-08-10

React-dApp, побудований на `@solana/wallet-adapter-react`, без проблем під'єднує десктопні гаманці, але на телефоні той самий сценарій ламається: гаманець має відкрити dApp у власному вбудованому браузері, а діплінки, які мали б це зробити, мовчки не спрацьовують. Backpack відкриває сторінку «завантажте застосунок»; Solflare відкриває застосунок, але ніколи — сайт; здається, що не працює жоден варіант. Ми розібрали проблему на частини, і виявилося, що це чотири окремі проблеми з одним спільним симптомом.

## Чотири проблеми
* Посилання для Backpack було сформоване неправильно. Єдиний задокументований формат — `https://backpack.app/ul/v1/browse/<url>?ref=<ref>`: універсальне посилання із цільовим URL у шляху та обов'язковим `ref`. Вгаданий варіант із власною схемою, як-от `backpack://ul/v1/browse?url=...`, не збігається з жодним маршрутом, який реєструє застосунок, тож користувач опиняється на сторінці встановлення гаманця.
* Solflare теж потребує свого універсального посилання: `https://solflare.com/ul/v1/browse/<url>?ref=<ref>`, а не голої схеми `solflare://`. Гола схема може запустити застосунок, не сказавши йому, що відкрити, — і виходить саме «застосунок відкривається, але вкладку із сайтом доводиться відкривати вручну».
* Обидва параметри мають бути закодовані. `url` — це повна абсолютна адреса dApp, а `ref` — походження (origin) сторінки, з якої надходить запит; кожен проходить через `encodeURIComponent`. Незакодований `?` або `&` у цільовій адресі ламає розбір, і гаманець відкривається на своєму головному екрані замість вкладки браузера.
* Спосіб запуску важить не менше за саме посилання. Універсальні посилання перемикають застосунки лише під час навігації, якій довіряє операційна система, — а вставлені в адресний рядок навмисно нічого не роблять; саме тому цілком коректне посилання під час тестування «не працює».

## Задокументовані формати
* Phantom: `https://phantom.app/ul/browse/<url>?ref=<ref>` — тут без `/v1`.
* Solflare: `https://solflare.com/ul/v1/browse/<url>?ref=<ref>`
* Backpack: `https://backpack.app/ul/v1/browse/<url>?ref=<ref>`

Один шаблон покриває всі три:

```js
const WALLET_BROWSE = {
  phantom: (url, ref) =>
    `https://phantom.app/ul/browse/${url}?ref=${ref}`,
  solflare: (url, ref) =>
    `https://solflare.com/ul/v1/browse/${url}?ref=${ref}`,
  backpack: (url, ref) =>
    `https://backpack.app/ul/v1/browse/${url}?ref=${ref}`,
};

function walletBrowseLink(
  walletName,
  targetUrl = window.location.href,
) {
  const build = WALLET_BROWSE[walletName.toLowerCase()];
  if (!build) return null;
  return build(
    encodeURIComponent(targetUrl),
    encodeURIComponent(window.location.origin),
  );
}
```

## Як запустити посилання, щоб iOS та Android його прийняли
* Виводьте справжнє посилання із заздалегідь обчисленою адресою. Звичайний `<a href={walletBrowseLink('phantom')}>` — найнадійніший спосіб запуску на обох платформах.
* Якщо потрібен програмний перехід, присвоюйте `window.location.href` синхронно всередині обробника натискання — без `await`, без `fetch`, без `setTimeout` перед цим. Після асинхронної роботи контекст жесту вже втрачено, і iOS натомість відкриває вебсайт гаманця. Ніколи не використовуйте `window.open`.
* Ніколи не тестуйте, вставляючи посилання в адресний рядок. Універсальні посилання там навмисно не спрацьовують; тестуйте натисканням на посилання або QR-кодом, відсканованим камерою.
* Зважайте на webview месенджерів. У вбудованому браузері Telegram чи Instagram універсальні посилання часто просто губляться, і натомість завантажується звичайний вебсайт гаманця. Визначення за user-agent — у кращому разі евристика, тож дайте користувачам ще й видимий запасний вихід: «відкрийте в Safari чи Chrome, а тоді під'єднайтеся».

## Ґрунтовніше виправлення на Android

Саморобні діплінки — це історія про iOS. На Android Mobile Wallet Adapter від Solana Mobile дає змогу dApp, що працює в мобільному браузері, під'єднатися безпосередньо до встановленого застосунку гаманця, взагалі без обхідного шляху через вбудований браузер. Свіжі версії `@solana/wallet-adapter-react` реєструють мобільний адаптер автоматично, тож оновлення пакетів wallet-adapter може саме собою виправити ситуацію на Android. Цільова архітектура: Mobile Wallet Adapter на Android, універсальні browse-посилання на iOS, де Apple не дозволяє нічого рівноцінного.

## Перевірка на пристрої

1. Справжній пристрій, встановлений гаманець, посилання відкрито із системного браузера — не з месенджера.
2. Натисніть посилання на сторінці або відскануйте QR-код; ніколи не вставляйте в адресний рядок.
3. Переконайтеся, що гаманець відкривається і dApp завантажується у вкладці його вбудованого браузера — саме друга половина і ламається.
4. Повторіть без встановленого гаманця: універсальне посилання має відкрити вебсайт гаманця як запасний варіант. Якщо ця сторінка з'являється, коли застосунок встановлено, — посилання або спосіб запуску все ще неправильні.
5. Потім перевірте шлях через месенджер і додайте підказку «відкрийте у браузері», якщо посилання там не спрацьовує.

## Джерела
* Phantom: діплінки на iOS та Android
* Solflare: діплінк Browse
* Backpack: діплінк Browse
* Solana Mobile: Mobile Wallet Adapter

=> https://docs.phantom.com/phantom-deeplinks/deeplinks-ios-and-android Phantom: діплінки на iOS та Android
=> https://docs.solflare.com/solflare/technical/deeplinks/other-methods/browse Solflare: діплінк Browse
=> https://docs.backpack.app/deeplinks/other-methods/browse Backpack: діплінк Browse
=> https://docs.solanamobile.com/mobile-wallet-adapter/mobile-apps Solana Mobile: Mobile Wallet Adapter

=> https://software.engineer.company/uk/notes/solana-mobile-wallet-deeplinks/ Ця сторінка у вебі
