Перейти до вмісту
EngineerСофтвер
Меню
Дизайн
Українська

Engineer / Софтвер / Блог

Як відкрити 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 не дозволяє нічого рівноцінного.

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

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

Джерела

Послуги

Контакти

Ще визначаєтесь, що саме вам потрібно?

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

Від 1 400 DKK за годину, без ПДВ — і дешевша година на довшому замовленні.

welcome@engineer.company +45 50 10 61 84 Копенгаген, Данія