{"canonical_url":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/","content_markdown":"# Solanaのモバイルウォレット内でdAppを開く\n\n2026-08-10\n\n`@solana/wallet-adapter-react`で構築したReactのdAppは、パソコンのウォレットには問題なく接続します。しかしスマートフォンでは、同じ手順がうまくいきません。ウォレット内のブラウザーでdAppを開く必要があるのに、それを行うはずのディープリンクが、何も言わず失敗します。Backpackでは「アプリをダウンロード」のページになり、Solflareではアプリは開いてもサイトが開きません。どの変形も失敗するように見えました。問題を分解すると、一つの症状に見える、四つの別々の問題でした。\n\n## 四つの問題\n\n- **Backpackのリンク形式が誤っていました。** 文書にある形式は`https://backpack.app/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`だけです。対象URLをパスに置き、`ref`を必須とするユニバーサルリンクです。推測した`backpack://ul/v1/browse?url=...`のような独自スキームは、アプリが登録するどのルートにも一致せず、ウォレットのインストールページに着きます。\n- **Solflareにもユニバーサルリンクが必要です。** `https://solflare.com/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`を使い、単なる`solflare://`スキームは使いません。スキームだけでは、アプリを起動しても移動先を指定できない場合があります。まさに「アプリは開くが、サイトのタブは手動で開く必要がある」という状態です。\n- **両方のパラメーターをエンコードする必要があります。** `url`はdAppの完全な絶対アドレス、`ref`は要求元のオリジンで、それぞれ`encodeURIComponent`を通します。対象URLにエンコードしていない`?`や`\u0026`があると解析が崩れ、ウォレットはブラウザータブではなくホーム画面を開きます。\n- **起動のきっかけも、リンク自体と同じくらい重要です。** ユニバーサルリンクがアプリを切り替えるのは、OSが信頼する移動操作のときだけです。アドレスバーに貼り付けても、意図的に何もしません。そのため、完全に正しいリンクもテスト中に「失敗」します。\n\n## 文書にある形式\n\n- Phantom：`https://phantom.app/ul/browse/\u003curl\u003e?ref=\u003cref\u003e`。この形式に`/v1`はありません。\n- Solflare：`https://solflare.com/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`\n- Backpack：`https://backpack.app/ul/v1/browse/\u003curl\u003e?ref=\u003cref\u003e`\n\n三つとも、同じパターンで扱えます。\n\n```js\nconst WALLET_BROWSE = {\n  phantom: (url, ref) =\u003e\n    `https://phantom.app/ul/browse/${url}?ref=${ref}`,\n  solflare: (url, ref) =\u003e\n    `https://solflare.com/ul/v1/browse/${url}?ref=${ref}`,\n  backpack: (url, ref) =\u003e\n    `https://backpack.app/ul/v1/browse/${url}?ref=${ref}`,\n};\n\nfunction walletBrowseLink(\n  walletName,\n  targetUrl = window.location.href,\n) {\n  const build = WALLET_BROWSE[walletName.toLowerCase()];\n  if (!build) return null;\n  return build(\n    encodeURIComponent(targetUrl),\n    encodeURIComponent(window.location.origin),\n  );\n}\n```\n\n## iOSとAndroidが受け入れる方法でリンクを開く\n\n- **事前計算した、本物のリンク要素を描画します。** 単純な`\u003ca href={walletBrowseLink('phantom')}\u003e`が、両方の環境で最も確実な起動方法です。\n- **プログラムから行う必要がある場合**は、タップのハンドラー内で、同期的に`window.location.href`へ代入します。その前に`await`、`fetch`、`setTimeout`を挟みません。非同期処理の後では操作の文脈が失われ、iOSはウォレットのウェブサイトへ移動します。`window.open`は使いません。\n- **アドレスバーへの貼り付けでは、決してテストしません。** ユニバーサルリンクは、そこでは意図的に動作しません。リンクをタップするか、カメラでQRコードを読み取ってテストします。\n- **メッセージアプリ内のウェブビューに注意します。** TelegramやInstagramのアプリ内ブラウザーでは、ユニバーサルリンクがしばしば処理されず、ウォレットの通常のウェブサイトが読み込まれます。ユーザーエージェントによる判定は、よくても推測にとどまります。そのため、「SafariまたはChromeで開いてから接続してください」という、見える回避方法も利用者に示します。\n\n## Androidでの、より根本的な修正\n\n独自のディープリンクを組み立てる方法は、iOS向けの話です。Androidでは、Solana MobileのMobile Wallet Adapterにより、モバイルブラウザーで動くdAppから、インストール済みのウォレットアプリへ直接接続でき、アプリ内ブラウザーを経由する必要はありません。最近の`@solana/wallet-adapter-react`は、モバイルアダプターを自動登録するため、wallet-adapter関連パッケージの更新だけでAndroidの問題が解消する場合もあります。目標の構成は、AndroidではMobile Wallet Adapter、相当する仕組みをAppleが認めていないiOSでは閲覧用ユニバーサルリンクです。\n\n## 実機での検証\n\n1. ウォレットをインストールした実機で、メッセージアプリではなくOSのブラウザーからリンクを開きます。\n2. 描画されたリンクをタップするか、QRコードを読み取ります。アドレスバーには貼り付けません。\n3. ウォレットが開き、そのアプリ内ブラウザーのタブにdAppが読み込まれることを確認します。失敗するのは、この後半です。\n4. ウォレットをインストールしていない状態でも繰り返します。ユニバーサルリンクは、ウォレットのウェブサイトに移動するはずです。インストール済みなのにそのページが出る場合は、リンクか起動方法がまだ誤っています。\n5. その後で、メッセージアプリ経由の動作をテストし、そこで失敗する場合は「ブラウザーで開く」案内を追加します。\n\n## 出典\n\n- [Phantom：iOSとAndroidのディープリンク](https://docs.phantom.com/phantom-deeplinks/deeplinks-ios-and-android)\n- [Solflare：Browseディープリンク](https://docs.solflare.com/solflare/technical/deeplinks/other-methods/browse)\n- [Backpack：Browseディープリンク](https://docs.backpack.app/deeplinks/other-methods/browse)\n- [Solana Mobile：Mobile Wallet Adapter](https://docs.solanamobile.com/mobile-wallet-adapter/mobile-apps)\n\n\u003chttps://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Phantom、Solflare、Backpackの閲覧用ディープリンクがモバイルで失敗する理由と、正しい形式、起動条件、修正方法を説明します。","formats":{"gemtext":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/index.gmi","gopher":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/gophermap","html":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/","json":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/index.json","markdown":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/index.md","pdf":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/index.pdf"},"kind":"page","language":"ja","title":"Solanaのモバイルウォレット内でdAppを開く","url":"https://engineer.company/ja/notes/solana-mobile-wallet-deeplinks/","version":1}