Navigator.registerProtocolHandler()

Limited availability

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

보안 컨텍스트: 이 기능은 일부 또는 모든 지원 브라우저보안 컨텍스트 (HTTPS)에서만 사용할 수 있습니다.

Navigator.registerProtocolHandler() 메서드는 웹 사이트가 특정 URL 스킴("프로토콜")을 열거나 처리할 수 있도록 등록합니다. 이를테면, 이메일 사이트가 mailto: URL에, VoIP 사이트가 tel: URL에 자신을 등록할 때 사용할 수 있습니다.

구문

js
navigator.registerProtocolHandler(protocol, url, title);

매개변수

protocol

웹 사이트가 처리하고자 하는 프로토콜 문자열. 예컨대 SMS 문자 메시지를 처리하고자 한다면 "sms"를 전달하세요.

url

처리기의 URL. 플레이스홀더로 사용할 %s를 반드시 포함해야 합니다. 실제 사용 시, %s에는 처리 대상 URL을 이스케이프 처리해 대입합니다.

참고 : 처리기의 URL은 반드시 http 또는 https 스킴을 필요로 합니다. 일부 브라우저는 보안상 https를 요구하므로 https를 사용하는 편이 좋습니다.

title

사람이 읽을 수 있는 형태의 처리기 이름. 브라우저 설정 등 처리기 목록에서 사용자에게 보이는 이름입니다.

예외

SecurityError

사용자 에이전트가 등록을 막았습니다. 다음 상황에서 발생할 수 있습니다.* 등록하려는 스킴(프로토콜)이 유효하지 않습니다. 브라우저가 직접 처리하는 스킴을 등록하려 하면 발생합니다. (https:, about:, ...)

  • 처리기 URL의 출처가 API를 호출한 페이지 출처와 일치하지 않습니다.
  • 브라우저가 보안 맥락에서의 registerProtocolHandler() 호출을 요구합니다.
  • 브라우저가 처리기 URL의 HTTPS 사용을 요구합니다.
SyntaxError

처리기 URL에 %s 플레이스홀더가 없습니다.

가능한 스킴

보안상의 이유로, registerProtocolHandler()가 등록할 수 있는 스킴은 제한적입니다.

사용자 지정 스킴은 다음 조건을 만족해야 합니다.

  • 스킴이 web+로 시작합니다.
  • web+ 접두사 뒤에 다른 글자가 최소 하나 존재해야 합니다.
  • 소문자 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: 스킴에 대한 처리기를 등록할 수 있습니다.

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

이제, web+burger: 링크는 사용자를 burgers.example.com로 보내고, 자신의 URL을 %s 위치에 삽입합니다.

이때, 예제 코드는 처리기 URL과 같은 출처를 가져야 하므로 https://burgers.example.com의 페이지 안에서 호출해야 하며, 처리기 URL은 http/https를 사용해야 합니다.

명세

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.