# Ouvrir une dApp via un portefeuille Solana mobile

2026-08-10

Une dApp React fondée sur `@solana/wallet-adapter-react` connecte sans difficulté les portefeuilles sur ordinateur, mais sur téléphone le même parcours se défait : le portefeuille doit ouvrir la dApp dans son propre navigateur intégré, et les liens profonds censés le permettre ne le font pas. Backpack aboutit à une page « télécharger l'application » ; Solflare ouvre l'application, mais jamais le site ; chaque variante semble échouer. Nous avons analysé le problème, qui s'est révélé être quatre problèmes distincts présentant un seul symptôme.

## Les quatre problèmes
* Le lien Backpack était mal formé. Le seul format documenté est `https://backpack.app/ul/v1/browse/<url>?ref=<ref>` — un lien universel avec l'URL cible dans le chemin et un `ref` obligatoire. Une supposition à base de schéma personnalisé comme `backpack://ul/v1/browse?url=...` ne correspond à aucune route enregistrée par l'application ; l'utilisateur arrive donc sur la page d'installation du portefeuille.
* Solflare nécessite aussi son lien universel : `https://solflare.com/ul/v1/browse/<url>?ref=<ref>`, plutôt que le simple schéma `solflare://`. Un schéma seul peut lancer l'application sans lui transmettre de route — précisément le cas où « l'application s'ouvre, mais il faut ouvrir manuellement l'onglet du site ».
* Les deux paramètres doivent être encodés. `url` est l'adresse absolue complète de la dApp et `ref` l'origine demandeuse, chacune passée à `encodeURIComponent`. Un `?` ou un `&` non encodé dans la cible corrompt l'analyse, et le portefeuille s'ouvre sur son écran d'accueil plutôt que sur l'onglet du navigateur.
* Le déclenchement compte autant que le lien. Les liens universels ne changent d'application que lors d'une navigation à laquelle le système d'exploitation fait confiance — et ne font délibérément rien lorsqu'ils sont collés dans la barre d'adresse. C'est aussi ainsi qu'un lien parfaitement correct « échoue » pendant les tests.

## Les formats documentés
* Phantom : `https://phantom.app/ul/browse/<url>?ref=<ref>` — pas de `/v1` dans celui-ci.
* Solflare : `https://solflare.com/ul/v1/browse/<url>?ref=<ref>`
* Backpack : `https://backpack.app/ul/v1/browse/<url>?ref=<ref>`

Un même modèle convient aux trois :

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

## Déclencher le lien pour qu'iOS et Android l'acceptent
* Affichez une véritable ancre dont la cible est précalculée. Un simple `<a href={walletBrowseLink('phantom')}>` est le déclencheur le plus fiable sur les deux plateformes.
* Si le déclenchement doit être programmatique, affectez `window.location.href` de manière synchrone dans le gestionnaire du toucher — aucun `await`, `fetch` ou `setTimeout` auparavant. Après un traitement asynchrone, le contexte du geste a disparu et iOS se rabat sur le site Web du portefeuille. Jamais de `window.open`.
* Ne testez jamais en collant dans la barre d'adresse. Les liens universels ne s'y déclenchent délibérément pas ; testez avec un lien touché ou un code QR scanné par l'appareil photo.
* Attention aux vues Web des messageries. Dans le navigateur intégré de Telegram ou d'Instagram, les liens universels sont souvent interceptés et le simple site Web du portefeuille se charge à leur place. La détection par user agent est au mieux heuristique ; donnez donc aussi aux utilisateurs une issue visible : « ouvrez dans Safari ou Chrome, puis connectez-vous ».

## La correction plus globale sur Android

Les liens profonds écrits à la main concernent iOS. Sur Android, Mobile Wallet Adapter de Solana Mobile permet à une dApp exécutée dans le navigateur mobile de se connecter directement à l'application de portefeuille installée, sans aucun détour par son navigateur intégré. Les versions récentes de `@solana/wallet-adapter-react` enregistrent automatiquement l'adaptateur mobile ; mettre à jour les paquets wallet-adapter peut donc suffire à corriger Android. L'architecture visée : Mobile Wallet Adapter sur Android et liens universels de navigation sur iOS, où Apple ne permet aucun équivalent.

## Vérifier sur un appareil

1. Appareil réel, portefeuille installé, lien ouvert depuis le navigateur système — pas depuis une messagerie.
2. Touchez un lien affiché ou scannez un code QR ; ne collez jamais dans la barre d'adresse.
3. Confirmez que le portefeuille s'ouvre et que la dApp se charge dans l'onglet de son navigateur intégré — c'est la seconde moitié qui échoue.
4. Répétez sans portefeuille installé : le lien universel doit se rabattre sur le site Web du portefeuille. Si cette page apparaît alors que l'application est installée, le lien ou son déclenchement est encore incorrect.
5. Testez ensuite le parcours depuis une messagerie et ajoutez l'indication « ouvrir dans le navigateur » s'il y échoue.

## Sources
* Phantom : liens profonds sur iOS et Android
* Solflare : le lien profond Browse
* Backpack : le lien profond Browse
* Solana Mobile : Mobile Wallet Adapter

=> https://docs.phantom.com/phantom-deeplinks/deeplinks-ios-and-android Phantom : liens profonds sur iOS et Android
=> https://docs.solflare.com/solflare/technical/deeplinks/other-methods/browse Solflare : le lien profond Browse
=> https://docs.backpack.app/deeplinks/other-methods/browse Backpack : le lien profond Browse
=> https://docs.solanamobile.com/mobile-wallet-adapter/mobile-apps Solana Mobile : Mobile Wallet Adapter

=> https://software.engineer.company/fr/notes/solana-mobile-wallet-deeplinks/ Cette page sur le Web
