Sådan åbner man en dApp i Solana-mobilwallets

En React-dApp bygget på @solana/wallet-adapter-react forbinder desktop-wallets uden problemer, men på en telefon falder det samme flow fra hinanden: wallet’en skal åbne dApp’en i sin egen indbyggede browser, og de deeplinks, der skulle klare det, virker bare ikke. Backpack lander på en “hent appen”-side; Solflare åbner appen, men aldrig sitet; alle varianter ser ud til at fejle. Vi skilte problemet ad, og det viste sig at være fire adskilte problemer med ét fælles symptom.

De fire problemer

  • Backpack-linket var forkert bygget. Det eneste dokumenterede format er https://backpack.app/ul/v1/browse/<url>?ref=<ref> — et universelt link med mål-URL’en i stien og et påkrævet ref. Et gæt med eget skema som backpack://ul/v1/browse?url=... matcher ingen rute i appen, så brugeren ender på wallet’ens installationsside.
  • Solflare skal også bruge sit universelle link: https://solflare.com/ul/v1/browse/<url>?ref=<ref> — ikke det rå solflare://-skema. Et råt skema kan starte appen uden at dirigere den — hvilket er præcis “appen åbner, men site-fanen må åbnes med hånden”.
  • Begge parametre skal være kodet. url er dApp’ens fulde absolutte adresse, og ref er den kaldende origin, hver især gennem encodeURIComponent. Et ukodet ? eller & i målet ødelægger fortolkningen, og wallet’en åbner på sin forside i stedet for browserfanen.
  • Udløsningen betyder lige så meget som linket. Universelle links skifter kun app ved en navigation, styresystemet stoler på — og de gør med vilje ingenting, når de indsættes i adresselinjen, hvilket også er sådan, et helt korrekt link “fejler” under test.

De dokumenterede formater

  • Phantom: https://phantom.app/ul/browse/<url>?ref=<ref> — uden /v1 i netop dette.
  • Solflare: https://solflare.com/ul/v1/browse/<url>?ref=<ref>
  • Backpack: https://backpack.app/ul/v1/browse/<url>?ref=<ref>

Ét mønster dækker alle tre:

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),
  );
}

Udløs linket, så iOS og Android accepterer det

  • Render et rigtigt anker, beregnet på forhånd. Et almindeligt <a href={walletBrowseLink('phantom')}> er den mest pålidelige udløser på begge platforme.
  • Skal det ske programmatisk, så tildel window.location.href synkront inde i tryk-handleren — ingen await, ingen fetch, ingen setTimeout først. Efter asynkront arbejde er gestus-konteksten væk, og iOS falder tilbage til wallet’ens websted. Aldrig window.open.
  • Test aldrig ved at indsætte i adresselinjen. Universelle links udløses med vilje ikke dér; test med et link, der trykkes på, eller en QR-kode, som kameraet scanner.
  • Pas på messenger-webviews. Åbnet i Telegrams eller Instagrams indbyggede browser bliver universelle links ofte slugt, og wallet’ens almindelige websted indlæses i stedet. User-agent-detektion er i bedste fald et gæt, så giv også brugerne en synlig nødudgang: “åbn i Safari eller Chrome, og forbind derefter”.

Den større løsning på Android

Håndbyggede deeplinks er iOS-historien. På Android lader Solana Mobiles Mobile Wallet Adapter en dApp i mobilbrowseren forbinde direkte til den installerede wallet-app, helt uden omvejen om den indbyggede browser. Nyere versioner af @solana/wallet-adapter-react registrerer mobiladapteren automatisk, så en opgradering af wallet-adapter-pakkerne kan løse Android alene. Målarkitekturen: Mobile Wallet Adapter på Android, universelle browse-links på iOS, hvor Apple ikke tillader en tilsvarende løsning.

Efterprøv på en enhed

  1. Rigtig enhed, wallet installeret, link åbnet fra systembrowseren — ikke fra en messenger.
  2. Tryk på et renderet link, eller scan en QR-kode; indsæt aldrig i adresselinjen.
  3. Bekræft, at wallet’en åbner, og at dApp’en indlæses i dens indbyggede browserfane — anden halvdel er den, der fejler.
  4. Gentag uden wallet’en installeret: det universelle link skal falde tilbage til wallet’ens websted. Ser du dén side, mens appen er installeret, er linket eller udløsningen stadig forkert.
  5. Test derefter messenger-vejen, og tilføj “åbn i browser”-hjælpen, hvis den fejler dér.

Kilder

Det er præcis den slags problemer, vi løser for vores kunder. Kontakt os.

Alle noter