Solanaのモバイルウォレット内でdAppを開く
2026-08-10

`@solana/wallet-adapter-react`で構築したReactのdAppは、パソコンの
ウォレットには問題なく接続します。しかしスマートフォンでは、同じ手順
がうまくいきません。ウォレット内のブラウザーでdAppを開く必要があるの
に、それを行うはずのディープリンクが、何も言わず失敗します。Backpack
では「アプリをダウンロード」のページになり、Solflareではアプリは開い
てもサイトが開きません。どの変形も失敗するように見えました。問題を分
解すると、一つの症状に見える、四つの別々の問題でした。

四つの問題

  * Backpackのリンク形式が誤っていました。
文書にある形式は`https://backpack.app/ul/v1/browse/<url>?ref=<ref>`
だけです。対象URLをパスに置き、`ref`を必須とするユニバーサルリンクで
す。推測した`backpack://ul/v1/browse?url=...`のような独自スキーム
は、アプリが登録するどのルートにも一致せず、ウォレットのインストール
ページに着きます。

  * Solflareにもユニバーサルリンクが必要です。
`https://solflare.com/ul/v1/browse/<url>?ref=<ref>`を使い、単なる
`solflare://`スキームは使いません。スキームだけでは、アプリを起動し
ても移動先を指定できない場合があります。まさに「アプリは開くが、サイ
トのタブは手動で開く必要がある」という状態です。

  * 両方のパラメーターをエンコードする必要があります。
`url`はdAppの完全な絶対アドレス、`ref`は要求元のオリジンで、それぞれ
`encodeURIComponent`を通します。対象URLにエンコードしていない`?`や
`&`があると解析が崩れ、ウォレットはブラウザータブではなくホーム画面
を開きます。

  * 起動のきっかけも、リンク自体と同じくらい重要です。
ユニバーサルリンクがアプリを切り替えるのは、OSが信頼する移動操作のと
きだけです。アドレスバーに貼り付けても、意図的に何もしません。そのた
め、完全に正しいリンクもテスト中に「失敗」します。

文書にある形式

  *
Phantom：`https://phantom.app/ul/browse/<url>?ref=<ref>`。この形式に
`/v1`はありません。

  * Solflare：`https://solflare.com/ul/v1/browse/<url>?ref=<ref>`

  * Backpack：`https://backpack.app/ul/v1/browse/<url>?ref=<ref>`

三つとも、同じパターンで扱えます。

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

iOSとAndroidが受け入れる方法でリンクを開く

  * 事前計算した、本物のリンク要素を描画します。 単純な`<a
href={walletBrowseLink('phantom')}>`が、両方の環境で最も確実な起動方
法です。

  *
プログラムから行う必要がある場合は、タップのハンドラー内で、同期的に
`window.location.href`へ代入します。その前に`await`、`fetch`、
`setTimeout`を挟みません。非同期処理の後では操作の文脈が失われ、iOS
はウォレットのウェブサイトへ移動します。`window.open`は使いません。

  * アドレスバーへの貼り付けでは、決してテストしません。
ユニバーサルリンクは、そこでは意図的に動作しません。リンクをタップす
るか、カメラでQRコードを読み取ってテストします。

  * メッセージアプリ内のウェブビューに注意します。
TelegramやInstagramのアプリ内ブラウザーでは、ユニバーサルリンクがし
ばしば処理されず、ウォレットの通常のウェブサイトが読み込まれます。
ユーザーエージェントによる判定は、よくても推測にとどまります。そのた
め、「SafariまたはChromeで開いてから接続してください」という、見える
回避方法も利用者に示します。

Androidでの、より根本的な修正

独自のディープリンクを組み立てる方法は、iOS向けの話です。Androidで
は、Solana MobileのMobile Wallet
Adapterにより、モバイルブラウザーで動くdAppから、インストール済みの
ウォレットアプリへ直接接続でき、アプリ内ブラウザーを経由する必要はあ
りません。最近の`@solana/wallet-adapter-react`は、モバイルアダプター
を自動登録するため、wallet-adapter関連パッケージの更新だけでAndroid
の問題が解消する場合もあります。目標の構成は、AndroidではMobile
Wallet Adapter、相当する仕組みをAppleが認めていないiOSでは閲覧用ユニ
バーサルリンクです。

実機での検証

1. ウォレットをインストールした実機で、メッセージアプリではなくOSの
ブラウザーからリンクを開きます。

2. 描画されたリンクをタップするか、QRコードを読み取ります。アドレス
バーには貼り付けません。

3. ウォレットが開き、そのアプリ内ブラウザーのタブにdAppが読み込まれ
ることを確認します。失敗するのは、この後半です。

4.
ウォレットをインストールしていない状態でも繰り返します。ユニバーサル
リンクは、ウォレットのウェブサイトに移動するはずです。インストール済
みなのにそのページが出る場合は、リンクか起動方法がまだ誤っています。

5. その後で、メッセージアプリ経由の動作をテストし、そこで失敗する場
合は「ブラウザーで開く」案内を追加します。

出典

  * Phantom：iOSとAndroidのディープリンク

  * Solflare：Browseディープリンク

  * Backpack：Browseディープリンク

  * Solana Mobile：Mobile Wallet Adapter

hこのページのウェブ版	URL:https://software.engineer.company/ja/notes/solana-mobile-wallet-deeplinks/	software.engineer.company	70
