Å åpne en dApp i Solana-lommebøker på mobil

En React-dApp bygd på @solana/wallet-adapter-react kobler seg til lommebøker på datamaskinen uten problemer, men på en telefon faller den samme flyten fra hverandre: lommeboken må åpne dApp-en i sin egen innebygde nettleser, og dyplenkene som skulle få det til, svikter i det stille. Backpack havner på en «last ned appen»-side; Solflare åpner appen, men aldri nettstedet; hver variant ser ut til å svikte. Vi tok problemet fra hverandre, og det viste seg å være fire separate problemer med ett felles symptom.

De fire problemene

• Backpack-lenken var feil bygd. Det eneste dokumenterte formatet er https://backpack.app/ul/v1/browse/<url>?ref=<ref> — en universell lenke med mål-URL-en i stien og en påkrevd ref. Et gjettet eget skjema som backpack://ul/v1/browse?url=... treffer ingen rute appen registrerer, så brukeren havner på installasjonssiden til lommeboken.
• Solflare trenger også sin universelle lenke: https://solflare.com/ul/v1/browse/<url>?ref=<ref>, ikke det nakne solflare://-skjemaet. Et nakent skjema kan starte appen uten å rute den videre — og det er nøyaktig «appen åpnes, men fanen med nettstedet må åpnes for hånd».
• Begge parameterne må kodes. url er den fullstendige, absolutte adressen til dApp-en, og ref er origin for siden som sender forespørselen, begge sendt gjennom encodeURIComponent. Et ukodet ? eller & i målet ødelegger tolkningen, og lommeboken åpner på startskjermen sin i stedet for i nettleserfanen.
• Utløseren betyr like mye som lenken. Universelle lenker bytter bare app ved en navigasjon operativsystemet stoler på — og de gjør med vilje ingenting når de limes inn i adressefeltet, som også er måten en helt korrekt lenke «svikter» på under testing.

De dokumenterte formatene

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

Ett mønster dekker 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),
  );
}

Utløs lenken slik at iOS og Android godtar den

• Gjengi et ekte anker, beregnet på forhånd. Et vanlig <a href={walletBrowseLink('phantom')}> er den mest pålitelige utløseren på begge plattformene.
• Må det skje programmatisk, så tilordne window.location.href synkront inne i håndtereren for trykket — ingen await, ingen fetch, ingen setTimeout først. Etter asynkront arbeid er gestkonteksten borte, og iOS faller tilbake til nettstedet til lommeboken. Aldri window.open.
• Test aldri ved å lime inn i adressefeltet. Universelle lenker utløses med vilje ikke der; test med en lenke du trykker på, eller en QR-kode som kameraet skanner.
• Pass på webvisningene i meldingsapper. Åpnet i den innebygde nettleseren til Telegram eller Instagram blir universelle lenker ofte slukt, og det vanlige nettstedet til lommeboken lastes i stedet. Gjenkjenning ut fra user agent er i beste fall heuristisk, så gi også brukerne en synlig nødutgang: «åpne i Safari eller Chrome, og koble til etterpå».

Den større løsningen på Android

Håndlagde dyplenker er iOS-historien. På Android lar Solana Mobiles Mobile Wallet Adapter en dApp som kjører i mobilnettleseren, koble seg rett til den installerte lommebokappen, helt uten omveien om en innebygd nettleser. Nyere versjoner av @solana/wallet-adapter-react registrerer mobiladapteren automatisk, så en oppgradering av wallet-adapter-pakkene kan løse Android på egen hånd. Målarkitekturen: Mobile Wallet Adapter på Android, universelle browse-lenker på iOS, der Apple ikke tillater noe tilsvarende.

Verifisering på en enhet

1. Ekte enhet, lommebok installert, lenken åpnet fra systemnettleseren — ikke fra en meldingsapp.
2. Trykk på en gjengitt lenke eller skann en QR-kode; lim aldri inn i adressefeltet.
3. Bekreft at lommeboken åpnes og at dApp-en lastes i nettleserfanen i appen — den andre halvdelen er den som svikter.
4. Gjenta uten lommeboken installert: den universelle lenken skal falle tilbake til nettstedet til lommeboken. Dukker den siden opp mens appen er installert, er lenken eller utløseren fortsatt feil.
5. Test deretter veien via meldingsappen, og legg til «åpne i nettleseren»-hintet hvis den svikter der.

Kilder

• Phantom: dyplenker på iOS og Android
• Solflare: Browse-dyplenken
• Backpack: Browse-dyplenken
• Solana Mobile: Mobile Wallet Adapter