Як відкрити 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

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