Aller au contenu
EngineerLogiciels
Menu
Design
Français

Engineer / Logiciels / Blog

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 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 :

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

Prestations

Contact

Vous cherchez encore à préciser vos besoins ?

Dites-nous ce qui ne fonctionne pas ou ce que vous essayez de construire. Nous vous dirons ce que cela demanderait, son coût approximatif et si nous sommes les bonnes personnes pour le réaliser.

À partir de 1 400 DKK de l'heure, hors TVA — et un tarif horaire réduit pour une réservation plus longue.

welcome@engineer.company +45 50 10 61 84 Copenhague, Danemark