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 完全対応 67Safari 未対応 なしWebView Android 未対応 なしChrome Android 未対応 なしFirefox Android 未対応 なしOpera Android 未対応 なしSafari iOS 未対応 なしSamsung Internet Android 未対応 なし

凡例

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

関連情報