iOS Safari opens metamask.io instead of metamask:// on connect() — deeplink fires outside the user-gesture window

[alnoki]

Affected versions

• @metamask/connect-multichain@0.15.0
• @metamask/connect-solana@1.2.0 (which depends on the above)

Reproduced on current iOS Safari on iPhone.

Symptom

A dapp calls Wallet Standard connect() on the MetaMask Connect connector from inside a user tap handler. Sometimes (more often on a cold first-of-day load) Safari navigates the current tab to https://metamask.io instead of handing off to the MetaMask iOS app via the metamask:// custom scheme. Refresh or wait and retry usually gets a successful hand-off; the failure rate is latency-correlated.

Phantom and other wallets on iOS Safari are unaffected (when they have a working universal-link / sync-deeplink path).

A sister bug exists for signMessage / sendCalls / writeContract after a successful connect: #252.

Root cause

iOS Safari only honors a navigation to a custom scheme (metamask://…) when the navigation runs inside the synchronous task that originated from the user's tap. Once any awaited promise resolves first (or a setTimeout callback fires), the gesture token is lost — Safari treats the window.location.href = '…' assignment as a programmatic navigation and resolves the host (metamask.io) in the current tab instead of handing off to the app.

In _deeplinkConnect (@metamask/connect-multichain/dist/src/multichain/index.js, around lines 700-770) the deeplink is opened on either of two paths, both of which exit the gesture window:

1. Warm transport — schedules the open on a 250 ms setTimeout:

   if (this.transport.isConnected()) {
     timeout = setTimeout(() => {
       this.openSimpleDeeplinkIfNeeded();
     }, 250);
   }

   The 250 ms delay alone is enough to exit Safari's gesture-token window on every call.

2. Cold transport — registers a one-shot listener and waits for the relay's session_request before opening:

   this.dappClient.once('session_request', (sessionRequest) => {
     const deeplink      = this.options.ui.factory.createConnectionDeeplink(connectionRequest);
     const universalLink = this.options.ui.factory.createConnectionUniversalLink(connectionRequest);
     openDeeplink(this.options, deeplink, universalLink);
   });
   return this.transport.connect({ scopes, … }).then(resolve)…

   On a cold WS/TLS the awaited transport.connect() plus the session_request round-trip routinely takes 300-800 ms.

openDeeplink (@metamask/connect-multichain/dist/src/multichain/utils/index.js, ~line 67) resolves to window.location.href = deeplink. By the time Safari sees that assignment, the gesture is already gone — so the navigation falls back to host resolution.

Why intermittent

Handshake latency varies. On a warm relay the 250 ms timer can still squeak past Safari on some iOS builds; on a cold relay (first-of-day, slow network, ad-block intercepting endpoints) it spills past the gesture window every time. That matches the "works sometimes, refresh and retry" symptom reported by our end users.

Reproduction

1. Dapp using @metamask/connect-solana@1.2.0 (or @metamask/connect-evm with the same underlying multichain client).
2. iOS Safari, MetaMask iOS app installed.
3. Tap a button whose onClick calls the Wallet Standard connect() feature.
4. On cold relay (Settings → Safari → Clear History; first connect of session), observe Safari navigates to https://metamask.io in the current tab instead of opening the MetaMask app.
5. Refresh, wait a few seconds, retry — usually succeeds.

Suggested fix shape

The fundamental constraint is: on iOS Safari, the metamask:// navigation must run synchronously inside the user-gesture task. That means either the SDK opens it sync, or it gives the dapp the URL to open sync.

Either of:

1. Pre-allocate the session on createSolanaClient so the connect URL is known without a relay round-trip. The dapp then calls a sync connector.getConnectUrl() and does window.location.href = url inside its own onClick. The existing async handshake continues in parallel; the MetaMask app, now foregrounded, completes the session via the relay.

2. Have connect() return the URL synchronously before awaiting, e.g. as a callback option or via the existing mobile.preferredOpenLink hook — but invoked before the handshake, with the URL ready. Today preferredOpenLink is only called inside the session_request listener, so this still misses the gesture window; moving the call earlier would fix it.

Notes

• mobile.preferredOpenLink (around line 743) lets the dapp choose how to open the URL but doesn't help with the gesture-loss timing — by the time it's called, the gesture is already gone.
• A workaround dapps can apply today: gate the MetaMask row in their wallet picker on registerMetaMaskConnect() completion, so users can't tap before the SDK has finished initializing. That prevents one cold-start failure mode but does not fix the gesture-window race; the relay-handshake path still loses it.

[tienkane]

We hit the same gesture-window problem on iOS Safari and worked around it, but doing so surfaced two further problems that the proposed "open synchronously within the tap handler" fix won't solve on its own. Sharing in case it helps scope the real fix.

Setup: @metamask/connect-evm@2.1.0 → @metamask/connect-multichain@1.1.0, via wagmi@3.6.20's metaMask() connector. Regular iOS Safari (not the MetaMask in-app browser). This is the MWP SDK deeplink path, not WalletConnect — see the code refs below (calling this out because similar "address invalid" reports get deflected to WalletConnect/Privy, e.g. MetaMask/metamask-sdk#1042).

Workaround for the gesture window: instead of letting the SDK open the link from its async preferredOpenLink callback (which, as this issue describes, fires after the relay session_request round-trip, outside the user gesture → Safari resolves it as a web URL), we surface the link to our own UI and render it as an <a> the user taps. The tap is a real gesture, so the app now opens reliably. But then:

Problem 1 — the Universal Link opens the app with no pairing request.
createConnectionUniversalLink builds https://metamask.app.link/connect/mwp?p=<payload>&c=1 (METAMASK_CONNECT_BASE_URL = "https://metamask.app.link/connect"). metamask.app.link is a Branch link, and the Branch handoff to the app drops arbitrary query params (it keeps only Branch's own params + link_click_id). So p/c never reach the app and MetaMask opens to its home screen with no connection prompt, even when installed and even with a valid user gesture. (Same symptom as MetaMask/metamask-sdk#439, though that one was the Unity SDK.)

Problem 2 — the custom scheme errors when the app isn't installed.
The only link that actually delivers the payload is the custom scheme createConnectionDeeplink → metamask://connect/mwp?p=<payload>&c=1 (METAMASK_DEEPLINK_BASE = "metamask://connect"), which is what mobile.preferredOpenLink(deeplink) receives. It opens the approval screen correctly when installed, but iOS Safari shows "Safari cannot open the page because the address is invalid" when no app handles the scheme (not installed). There is no way for a dapp to suppress that dialog or to detect install state from the web, so neither link is correct for both states (cf. #252).

Net: a dapp on iOS mobile web is forced to choose between "connect works but errors when not installed" (custom scheme) and "no error but never connects when installed" (Branch universal link). The gesture-window fix alone doesn't resolve this — even a perfectly-timed tap on the universal link still loses the payload.

Suggested fix (one change covers all three): serve the connect deep link as a first-party Universal Link backed by MetaMask's own apple-app-site-association / Android App Links (e.g. on link.metamask.io, not routed through Branch), so the full URL incl. p/c reaches the app's continueUserActivity handler intact. A proper first-party universal link:

• opens the installed app on the approval screen with the payload (fixes Problem 1),
• falls back to a web page / store when not installed, with no "address invalid" dialog (fixes Problem 2), and
• is honored when opened from a real user tap, which is the reliable path through the gesture window this issue is about.

[adonesky1]

@alnoki @tienkane neither of you are setting useDeepLink to false in your constructors right? Currently that's the only way I'm seeing that you could be seeing universal links reached?

[alnoki]

Thanks for taking a look, @adonesky1.

No — we're not setting useDeeplink (or preferredOpenLink). We call createSolanaClient({ dapp, api, analytics }) with no mobile block, so we're on the default, which openDeeplink resolves to mobile?.useDeeplink ?? true → the metamask:// custom scheme, not the universal link.

One thing that may be feeding the confusion here: the JSDoc on the option (the types.ts lines linked above) says "if false (the default for web) … universal link", but the code defaults to true and both package READMEs say "default: true" — so that "default for web" note looks off.

For what it's worth: digging in on our side, much of the "opens metamask.io" behavior we reported traces to our own dapp's install-link fallback (shown before the relay connector finishes registering), not the SDK deeplink. I haven't isolated a clean SDK-side gesture-window repro beyond that, so please take our original report with a grain of salt — I'll follow up here if we get a solid reproduction. Thanks again.

[tienkane]

Thanks @adonesky1 — you're right, and this clears it up on our side too.

No, we're not setting useDeeplink: false. The universal link was self-inflicted, not the SDK: we set mobile.preferredOpenLink, which the SDK correctly calls with the custom scheme (createConnectionDeeplink → metamask://connect/mwp?…). Our own handler was then rewriting that to https://metamask.app.link/… (to try to get an app-store fallback for users without the app) — and that's what routed us through Branch and dropped p/c. Removing the rewrite and passing the metamask:// scheme straight through makes MetaMask open on the pairing screen as expected. So please disregard my "Problem 1" above — that was our bug, not the SDK.

What remains — and is the reason we were rewriting in the first place: with the metamask:// custom scheme, iOS Safari shows "…the address is invalid" when the app isn't installed, and a dapp can't detect install state or suppress that dialog. The only universal-link alternative the SDK exposes (createConnectionUniversalLink) is on metamask.app.link (Branch), which drops the query params, so it can't double as a no-error fallback that still pairs. That's why a first-party, payload-preserving universal link (MetaMask's own AASA, not Branch) would help — it'd give "installed → open + pair, not-installed → web/store, no error" from a single link. Not a blocker for us anymore (we ship the custom scheme plus a separate install link), just the gap that pushed us down the wrong path.

Also +1 to @alnoki's note on the useDeeplink JSDoc: it says "if false (the default for web) … universal link", but the code defaults to true and the READMEs say "default: true" — the "default for web" wording looks like a doc bug.