Abrir una dApp en wallets móviles de Solana
2026-08-10

Una dApp React basada en `@solana/wallet-adapter-react` conecta
wallets de escritorio sin problemas, pero en el teléfono el mismo
flujo se deshace: la wallet debe abrir la dApp en su navegador
integrado y los enlaces profundos que deberían hacerlo no funcionan,
sin más. Backpack acaba en una página con «download the app»;
Solflare abre la aplicación, pero nunca el sitio. Todas las
variantes parecen fallar. Desmenuzamos el problema y resultaron ser
cuatro problemas distintos con un mismo síntoma.

Los cuatro problemas

  * El enlace de Backpack estaba mal formado. El único formato
documentado es `https://backpack.app/ul/v1/browse/<url>?ref=<ref>`:
un enlace universal con la URL de destino en la ruta y un `ref`
obligatorio. Una suposición con un esquema propio, como
`backpack://ul/v1/browse?url=...`, no coincide con ninguna ruta
registrada por la aplicación, así que el usuario acaba en la página
de instalación de la wallet.

  * Solflare también necesita su enlace universal:
`https://solflare.com/ul/v1/browse/<url>?ref=<ref>`, no el esquema
`solflare://` a secas. Un esquema sin más puede iniciar la
aplicación sin dirigirla al destino: justamente el caso en que se
abre la aplicación, pero hay que abrir la pestaña del sitio a mano.

  * Ambos parámetros deben codificarse. `url` es la dirección
absoluta completa de la dApp y `ref` el origen solicitante; ambos
pasan por `encodeURIComponent`. Un `?` o `&` sin codificar en el
destino altera el análisis y la wallet abre su pantalla de inicio en
lugar de la pestaña del navegador.

  * El activador importa tanto como el enlace. Los enlaces
universales solo cambian de aplicación en una navegación que el
sistema operativo considera fiable. Deliberadamente no hacen nada al
pegarlos en la barra de direcciones, y así un enlace perfectamente
correcto también puede parecer que falla durante una prueba.

Los formatos documentados

  * Phantom: `https://phantom.app/ul/browse/<url>?ref=<ref>`, sin
`/v1` en este caso.

  * Solflare: `https://solflare.com/ul/v1/browse/<url>?ref=<ref>`

  * Backpack: `https://backpack.app/ul/v1/browse/<url>?ref=<ref>`

Un patrón sirve para los tres:

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

Activar el enlace de forma que iOS y Android lo acepten

  * Muestre un enlace real, calculado de antemano. Un sencillo `<a
href={walletBrowseLink('phantom')}>` es el activador más fiable en
ambas plataformas.

  * Si debe hacerse por código, asigne `window.location.href` de
forma síncrona dentro del manejador del toque: sin `await`, `fetch`
ni `setTimeout` previos. Tras un trabajo asíncrono se pierde el
contexto del gesto e iOS vuelve al sitio de la wallet. Nunca use
`window.open`.

  * No pruebe pegando en la barra de direcciones. Los enlaces
universales no se activan ahí deliberadamente; pruebe tocando un
enlace o escaneando un código QR con la cámara.

  * Tenga en cuenta las vistas web de las aplicaciones de
mensajería. En los navegadores integrados de Telegram o Instagram,
los enlaces universales se interceptan con frecuencia y cargan el
sitio normal de la wallet. La detección del agente de usuario es,
como mucho, heurística; ofrezca también una salida visible: «abra en
Safari o Chrome y después conecte».

La solución más amplia en Android

Los enlaces profundos hechos a mano son la vía de iOS. En Android,
Mobile Wallet Adapter de Solana Mobile permite que una dApp en el
navegador móvil conecte directamente con la aplicación wallet
instalada, sin pasar por su navegador integrado. Las versiones
recientes de `@solana/wallet-adapter-react` registran el adaptador
móvil automáticamente, así que actualizar los paquetes de
wallet-adapter puede corregir Android por sí solo. La arquitectura
objetivo: Mobile Wallet Adapter en Android y enlaces universales
Browse en iOS, donde Apple no permite un equivalente.

Verificación en un dispositivo

1. Dispositivo real, wallet instalada y enlace abierto desde el
navegador del sistema, no desde una aplicación de mensajería.

2. Toque un enlace mostrado o escanee un código QR; nunca lo pegue
en la barra de direcciones.

3. Compruebe que la wallet se abre y que la dApp carga en su pestaña
de navegador integrada: la segunda parte es la que falla.

4. Repita sin la wallet instalada: el enlace universal debería
volver al sitio de la wallet. Si aparece esa página con la
aplicación instalada, el enlace o el activador siguen siendo
incorrectos.

5. Después pruebe la vía de mensajería y añada la indicación de
abrir en el navegador si falla ahí.

Fuentes

  * Phantom: enlaces profundos en iOS y Android

  * Solflare: el enlace profundo Browse

  * Backpack: el enlace profundo Browse

  * Solana Mobile: Mobile Wallet Adapter

hEsta página en la web	URL:https://engineer.company/es/notes/solana-mobile-wallet-deeplinks/	engineer.company	70
