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

hCette page sur le Web	URL:https://software.engineer.company/fr/notes/solana-mobile-wallet-deeplinks/	software.engineer.company	70
