Як відкрити dApp у мобільних гаманцях Solana
Чому діплінки Phantom, Solflare і Backpack для відкриття dApp не спрацьовують на телефоні: точні формати, правила запуску й виправлення, з якими вони працюють.
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>
Один шаблон покриває всі три:
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 не дозволяє нічого
рівноцінного.
Перевірка на пристрої
- Справжній пристрій, встановлений гаманець, посилання відкрито із системного браузера — не з месенджера.
- Натисніть посилання на сторінці або відскануйте QR-код; ніколи не вставляйте в адресний рядок.
- Переконайтеся, що гаманець відкривається і dApp завантажується у вкладці його вбудованого браузера — саме друга половина і ламається.
- Повторіть без встановленого гаманця: універсальне посилання має відкрити вебсайт гаманця як запасний варіант. Якщо ця сторінка з’являється, коли застосунок встановлено, — посилання або спосіб запуску все ще неправильні.
- Потім перевірте шлях через месенджер і додайте підказку «відкрийте у браузері», якщо посилання там не спрацьовує.