{"canonical_url":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/","content_markdown":"# Opening a dApp inside Solana mobile wallets\n\n2026-08-10\n\nA React dApp built on `@solana/wallet-adapter-react` connects desktop wallets\nwithout trouble, but on a phone the same flow falls apart: the wallet has to\nopen the dApp inside its own in-app browser, and the deep links that should\nmake that happen quietly do not. Backpack lands on a \"download the app\" page;\nSolflare opens the app but never the site; every variant seems to fail. We took\nthe problem apart, and it turned out to be four separate problems wearing one\nsymptom.\n\n## The four problems\n\n- **The Backpack link was malformed.** The only documented format is\n  `https://backpack.app/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e` — a universal link with\n  the target URL in the path and a required `ref`. A custom-scheme guess like\n  `backpack://ul/v1/browse?url=...` matches no route the app registers, so the\n  user ends on the wallet's install page.\n- **Solflare needs its universal link too:**\n  `https://solflare.com/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`, not the bare\n  `solflare://` scheme. A bare scheme can launch the app without routing it —\n  which is exactly \"the app opens, but the site tab has to be opened by hand\".\n- **Both parameters must be encoded.** `url` is the full absolute dApp address\n  and `ref` is the requesting origin, each passed through `encodeURIComponent`.\n  An unencoded `?` or `\u0026` in the target corrupts the parse, and the wallet\n  opens on its home screen instead of the browser tab.\n- **The trigger matters as much as the link.** Universal links only switch apps\n  on a navigation the operating system trusts — and they deliberately do\n  nothing when pasted into the address bar, which is also how a perfectly\n  correct link \"fails\" during testing.\n\n## The documented formats\n\n- Phantom: `https://phantom.app/ul/browse/\u003curl\u003e?ref=\u003cref\u003e` — no `/v1` in this\n  one.\n- Solflare: `https://solflare.com/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`\n- Backpack: `https://backpack.app/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`\n\nOne pattern serves all three:\n\n```js\nconst WALLET_BROWSE = {\n  phantom: (url, ref) =\u003e\n    `https://phantom.app/ul/browse/${url}?ref=${ref}`,\n  solflare: (url, ref) =\u003e\n    `https://solflare.com/ul/v1/browse/${url}?ref=${ref}`,\n  backpack: (url, ref) =\u003e\n    `https://backpack.app/ul/v1/browse/${url}?ref=${ref}`,\n};\n\nfunction walletBrowseLink(\n  walletName,\n  targetUrl = window.location.href,\n) {\n  const build = WALLET_BROWSE[walletName.toLowerCase()];\n  if (!build) return null;\n  return build(\n    encodeURIComponent(targetUrl),\n    encodeURIComponent(window.location.origin),\n  );\n}\n```\n\n## Triggering the link so iOS and Android accept it\n\n- **Render a real anchor, precomputed.** A plain\n  `\u003ca href={walletBrowseLink('phantom')}\u003e` is the most reliable trigger on both\n  platforms.\n- **If it must be programmatic**, assign `window.location.href` synchronously\n  inside the tap handler — no `await`, no `fetch`, no `setTimeout` first. After\n  asynchronous work the gesture context is gone, and iOS falls back to the\n  wallet's website. Never `window.open`.\n- **Never test by pasting into the address bar.** Universal links deliberately\n  do not fire there; test with a tapped link or a QR code scanned by the\n  camera.\n- **Mind the messenger webviews.** Opened inside Telegram's or Instagram's\n  in-app browser, universal links are frequently swallowed and the wallet's\n  plain website loads instead. User-agent detection is heuristic at best, so\n  also give users a visible escape hatch: \"open in Safari or Chrome, then\n  connect\".\n\n## The bigger fix on Android\n\nHand-rolled deep links are the iOS story. On Android, Solana Mobile's Mobile\nWallet Adapter lets a dApp running in the mobile browser connect straight to\nthe installed wallet app, with no in-app-browser detour at all. Recent versions\nof `@solana/wallet-adapter-react` register the mobile adapter automatically, so\nupgrading the wallet-adapter packages can fix Android by itself. The target\narchitecture: Mobile Wallet Adapter on Android, browse universal links on iOS,\nwhere Apple allows no equivalent.\n\n## Verifying on a device\n\n1. Real device, wallet installed, link opened from the system browser — not\n   from a messenger.\n2. Tap a rendered link or scan a QR code; never paste into the address bar.\n3. Confirm the wallet opens and the dApp loads in its in-app browser tab — the\n   second half is the part that fails.\n4. Repeat without the wallet installed: the universal link should degrade to\n   the wallet's website. That page appearing while the app is installed means\n   the link or the trigger is still wrong.\n5. Then test the messenger path, and add the \"open in browser\" hint if it\n   fails there.\n\n## Sources\n\n- [Phantom: deep links on iOS and Android](https://docs.phantom.com/phantom-deeplinks/deeplinks-ios-and-android)\n- [Solflare: the Browse deep link](https://docs.solflare.com/solflare/technical/deeplinks/other-methods/browse)\n- [Backpack: the Browse deep link](https://docs.backpack.app/deeplinks/other-methods/browse)\n- [Solana Mobile: Mobile Wallet Adapter](https://docs.solanamobile.com/mobile-wallet-adapter/mobile-apps)\n\n\u003chttps://engineer.company/notes/solana-mobile-wallet-deeplinks/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"Why Phantom, Solflare and Backpack browse deep links fail on mobile, and the exact formats, trigger rules and fixes that make them work.","formats":{"gemtext":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/index.gmi","gopher":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/gophermap","html":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/","json":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/index.json","markdown":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/index.md","pdf":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/index.pdf"},"kind":"page","language":"en","title":"Opening a dApp inside Solana mobile wallets","url":"https://engineer.company/notes/solana-mobile-wallet-deeplinks/","version":1}