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 これは廃止された API であり、動作は保証されていません。
ハンドラーを表す人間が読めるタイトル文字列です。これは、「このサイトで [スキーム] リンクを扱うことを許可しますか?」というプロンプトや、ブラウザーの設定で登録されたハンドラーを一覧表示するなどの形でユーザーに表示されます
注: タイトルはなりすましの懸念から仕様から削除されましたが、現在のすべてのブラウザーではまだ必要とされています。更新された仕様に対応しているブラウザーはほとんどの場合、下位互換性があり、まだ受け付けている可能性が高いので、常にタイトルを設定しておくことをお勧めします (ただし、使用はしません)。

例外

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

ブラウザーの互換性

BCD tables only load in the browser

関連情報