Navigator: registerProtocolHandler() メソッド

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

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

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

プロトコルハンドラーを登録するには、ウェブサイトが registerProtocolHandler() を呼び出し、登録するプロトコルとテンプレート URL を渡します。

ユーザーが登録されたプロトコルを使用するリンクを起動すると、ブラウザーはハンドラー登録時に指定された URL テンプレートに起動したリンクの href を挿入し、現在のページを生成された URL に移動します。

ブラウザーは、プロトコルが登録されたとき、またはユーザーがリンクを起動したときに、ページがプロトコルを処理することを許可するかどうかを確認するようユーザーに要求することがあります。

構文

js
registerProtocolHandler(scheme, url)

引数

scheme

サイトが扱いたいプロトコルのスキームが入った文字列です。

次のようなスキーム名のカスタムスキームにすることができます。

  • web+ で始まる
  • web+ 接頭辞の後に 1 文字以上ある
  • 小文字の ASCII 文字のみが含まれている

それ以外の場合はスキームは以下のいずれかでなければなりません。

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

ハンドラーの URL を指定する文字列。 この URL には %s を含める必要があり、これは取り扱う URL をエスケープしたもので置き換得られるプレイスホルダーとして扱われます。

ハンドラーの URL は https スキームを使用する必要があり、ハンドラーを登録しようとするウェブページと同じオリジンでなければなりません。

返値

なし (undefined)。

例外

SecurityError DOMException

ユーザーエージェントが登録をブロックしました。 以下のような場合に起こる可能性があります。

  • ブラウザーが自身が処理するスキーム(https:, about:, など)であるなど、登録されているスキーム(プロトコル)が無効である場合。
  • ハンドラーの URL のオリジンが、本 API を呼び出すページのオリジンと一致しない場合。
  • ブラウザーが、この関数を安全なコンテキストから呼び出すことを要求している場合。
  • ブラウザーが、ハンドラーの URL が HTTPS であることを要求している場合。
SyntaxError DOMException

%s が指定されたハンドラー URL に含まれていない場合。

mailto プロトコルのハンドラーを登録する

ウェブページが、https 以外のプロトコルを使用してリソースにリンクすることはよくあります。例えば、mailto: プロトコルなどです。ウェブ制作者は、ユーザーがウェブページから直接電子メールを送信できる便利な方法を提供したい場合に、mailto リンクを使用することができます。

html
<a href="mailto:webmaster@example.com">ウェブマスター</a>

リンクが有効になると、ブラウザーが既定のデスクトップアプリケーションを起動してメールを処理します。この処理を、デスクトップベースのプロトコルハンドラーと考えることができます。

ウェブベースのプロトコルハンドラーを使用すると、ウェブベースのアプリケーションも処理に参加できます。例えば、mail.example.org のウェブメールアプリは、次のようなコードで mailto リンクを処理するように登録できます。

js
navigator.registerProtocolHandler("mailto", "https://mail.example.org/?to=%s");

この後、ユーザーが任意のウェブサイト上の mailto リンクをクリックすると、ブラウザーは(確認を依頼するメッセージを表示するなどして) https://mail.example.org/?to=mailto:webmaster@example.com に移動します。このページでは、URL の引数を解釈してアドレスを抽出し、それをメールの初期化に使用することができます。

カスタムプロトコルのハンドラーを登録する

この例では、ページが web+burger プロトコルのハンドラーを次のようなコードで登録します。

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

その後、ユーザーはこのようなリンクが格納されたページにアクセスします。

html
<a href="web+burger:cheeseburger">cheeseburger</a>

ユーザーが web+burger リンクを起動すると、ブラウザーは(ユーザーに確認を要求した後) https://burgers.example.org/?burger=web+burger:cheeseburger に移動します。

仕様書

Specification
HTML
# custom-handlers

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
registerProtocolHandler
scheme parameter supports bitcoin
scheme parameter supports cabal
ExperimentalNon-standard
scheme parameter supports dat
ExperimentalNon-standard
scheme parameter supports did
ExperimentalNon-standard
scheme parameter supports dweb
ExperimentalNon-standard
scheme parameter supports ethereum
ExperimentalNon-standard
scheme parameter supports ftp
Experimental
scheme parameter supports ftps
Experimental
scheme parameter supports geo
scheme parameter supports hyper
ExperimentalNon-standard
scheme parameter supports im
scheme parameter supports ipfs
ExperimentalNon-standard
scheme parameter supports ipns
ExperimentalNon-standard
scheme parameter supports irc
scheme parameter supports ircs
scheme parameter supports magnet
scheme parameter supports mailto
scheme parameter supports matrix
scheme parameter supports mms
scheme parameter supports news
scheme parameter supports nntp
scheme parameter supports openpgp4fpr
scheme parameter supports sftp
Experimental
scheme parameter supports sip
scheme parameter supports sms
scheme parameter supports smsto
scheme parameter supports ssb
ExperimentalNon-standard
scheme parameter supports ssh
scheme parameter supports tel
scheme parameter supports urn
scheme parameter supports webcal
scheme parameter supports wtai
scheme parameter supports xmpp
Secure context required

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.