Ouvrir une dApp via un portefeuille Solana mobile
Pourquoi les liens de navigation Phantom, Solflare et Backpack échouent sur mobile : formats exacts, règles de déclenchement et corrections.
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 unrefobligatoire. Une supposition à base de schéma personnalisé commebackpack://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émasolflare://. 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.
urlest l’adresse absolue complète de la dApp etrefl’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/v1dans 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 :
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.hrefde manière synchrone dans le gestionnaire du toucher — aucunawait,fetchousetTimeoutauparavant. Après un traitement asynchrone, le contexte du geste a disparu et iOS se rabat sur le site Web du portefeuille. Jamais dewindow.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
- Appareil réel, portefeuille installé, lien ouvert depuis le navigateur système — pas depuis une messagerie.
- Touchez un lien affiché ou scannez un code QR ; ne collez jamais dans la barre d’adresse.
- 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.
- 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.
- Testez ensuite le parcours depuis une messagerie et ajoutez l’indication « ouvrir dans le navigateur » s’il y échoue.