Navigator.registerProtocolHandler()

安全なコンテキスト用
この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

NavigatorregisterProtocolHandler() メソッドは、ウェブサイトが特定の URL スキーム (別名プロトコル) を開いたり処理したりする能力を登録することを可能にします。

例えば、この API はウェブメールサイトを mailto: の URL で開かせたり、 VoIP サイトを tel: の URL で開かせたりします。

構文

navigator.registerProtocolHandler(scheme, url, title);
注: 最近になって navigator.registerProtocolHandler(scheme, url) と更新されましたが、こちらに対応しているブラウザーは今のところありませx。

引数

scheme
サイトが処理したいプロトコルを指定する文字列。例えば、 "sms" スキームを渡すことで、SMS テキストメッセージリンクを扱うように登録することができます。
url
ハンドラーの URL を指定する文字列。この文字列には、処理される文書の URL をエスケープした者で置き換えられるプレイスホルダー "%s" を含めてください。この URL は本物の URL のほか、電話番号、メールアドレスなどにすることもできます。
注: ハンドラー URL のスキームは https でなければなりません。ブラウザーによってはセキュリティのため、 HTTPS の URL であることを求めるため、そうするべきです
title
ハンドラーを表す人間が読めるタイトル文字列です。これは、「このサイトで [スキーム] リンクを扱うことを許可しますか?」というプロンプトや、ブラウザーの設定で登録されたハンドラーを一覧表示するなどの形でユーザーに表示されます
注: タイトルはなりすましの懸念から仕様から削除されましたが、現在のすべてのブラウザーではまだ必要とされています。更新された仕様に対応しているブラウザーはほとんどの場合、下位互換性があり、まだ受け付けている可能性が高いので、常にタイトルを設定しておくことをお勧めします (ただし、使用はしません)。

例外

SecurityError
ユーザーエージェントが登録をブロックしました。以下のような場合に起こる可能性があります。
  • ブラウザーが独自に処理するスキーム (https:, about:, など) など、登録されているスキーム (プロトコル) が無効です。
  • ハンドラーの URL のオリジンが、本 API を呼び出すページのオリジンと一致しない。
  • ブラウザーが、この関数を安全なコンテキストから呼び出す必要がある。
  • ブラウザーがハンドラーの URL が HTTPS 以上であることを要求している。
SyntaxError
%s が指定されたハンドラー URL に含まれていない。

許可されたスキーム

セキュリティ上の理由により registerProtocolHandler() は登録可能なスキームに制限を設けています。

カスタムスキームは次のような場合に登録されます。

  • カスタムスキームの名前が web+ で始まる
  • カスタムスキームの名前が web+ 接頭辞の後に1文字以上ある
  • カスタムスキームの名前に小文字の ASCII 文字のみが含まれている

例えば下の で使われている web+burger などが挙げられます。

もしくは、以下のホワイトリストに挙げられているスキームでなければなりません。

  • bitcoin
  • geo
  • im
  • irc
  • ircs
  • magnet
  • mailto
  • mms
  • news
  • nntp
  • openpgp4fpr
  • sip
  • sms
  • smsto
  • ssh
  • tel
  • urn
  • webcal
  • wtai
  • xmpp

ウェブアプリケーションが burgers.example.com にある場合、次のようにして web+burger: リンクを処理するプロトコルハンドラーを登録できます:

navigator.registerProtocolHandler("web+burger",
                                  "https://burgers.example.com/?burger=%s",
                                  "Burger handler");

これは、 web+burger: リンクがアクセスしたバーガーの URL を %s プレースホルダーに挿入し、ユーザーをサイトに誘導するハンドラーを作成します。

このスクリプトはハンドラーの URL と同じオリジン (すなわち、 https://burgers.example.com にあるページのいずれか) から実行する必要があり、ハンドラーの URL は http または https である必要があります。

あなたのコードがプロトコルハンドラーを登録しようとしていることはユーザーに通知され、ユーザーは登録を許可するかどうか決めることができます。以下のスクリーンショットは google.co.uk での例です。

A browser notification reads “Add Burger handler (www.google.co.uk) as an application for burger links?”, and offers an “Add Application” button and a close to ignore the handler request.

仕様書

仕様書 状態 備考
HTML Living Standard
registerProtocolHandler() の定義
現行の標準 Living standard

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
registerProtocolHandlerChrome 完全対応 13
補足
完全対応 13
補足
補足 Allowed schemes include mailto, mms, nntp, rtsp, and webcal. Custom protocols must be prefixed with web+.
補足 From Chrome 77, the URL parameter only accepts http or https URLs.
Edge 完全対応 ≤79
補足
完全対応 ≤79
補足
補足 Allowed schemes include mailto, mms, nntp, rtsp, and webcal. Custom protocols must be prefixed with web+.
Firefox 完全対応 3IE ? Opera 完全対応 11.6Safari ? WebView Android 未対応 なしChrome Android 未対応 なしFirefox Android 未対応 なしOpera Android ? Safari iOS 未対応 なしSamsung Internet Android 完全対応 あり
Secure context requiredChrome 完全対応 80Edge 完全対応 ≤79Firefox 完全対応 62IE ? Opera ? Safari ? WebView Android 未対応 なしChrome Android 未対応 なしFirefox Android 未対応 なしOpera Android ? Safari iOS 未対応 なしSamsung Internet Android 未対応 なし

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
実装ノートを参照してください。
実装ノートを参照してください。

関連情報