# 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](https://docs.phantom.com/phantom-deeplinks/deeplinks-ios-and-android)
- [Solflare: el enlace profundo Browse](https://docs.solflare.com/solflare/technical/deeplinks/other-methods/browse)
- [Backpack: el enlace profundo Browse](https://docs.backpack.app/deeplinks/other-methods/browse)
- [Solana Mobile: Mobile Wallet Adapter](https://docs.solanamobile.com/mobile-wallet-adapter/mobile-apps)

<https://engineer.company/es/notes/solana-mobile-wallet-deeplinks/>
