1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
---
title: Navigator.registerProtocolHandler()
slug: Web/API/Navigator/registerProtocolHandler
translation_of: Web/API/Navigator/registerProtocolHandler
---
<div>{{APIRef("HTML DOM")}}</div>
<p>In progress. Allows web sites to register themselves as possible handlers for particular protocols.</p>
<p>For security reasons, by default, web sites may only register protocol handlers for themselves — the domain and protocol of the handler must match the current site. However, users may set a preference in Firefox to allow cross website installation, by setting the <code>gecko.handlerService.allowRegisterFromDifferentHost</code> pref to <code>true</code> in about:config.</p>
<p>Extensions can register protocol handlers targeting other sites: see the 'See Also' section for how to use them from XPCOM.</p>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox">window.navigator.registerProtocolHandler(<em>protocol</em>, <em>url</em>, <em>title</em>);
</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
<dt><code>protocol</code></dt>
<dd>The protocol the site wishes to handle, specified as a string. For example, you can register to handle SMS text message links by registering to handle the "sms" scheme.</dd>
<dt><code>url</code></dt>
<dd>The URL of the handler, as a string. This string should include "%s" as a placeholder which will be replaced with the escaped URL of the document to be handled. This URL might be a true URL, or it could be a phone number, email address, or so forth.
<div class="note">The handler's URL must use one of "http" or "https" as its scheme.</div>
</dd>
<dt><code>title</code></dt>
<dd>A user-readable title string for the protocol handler. This will be displayed to the user in interface objects as needed.</dd>
</dl>
<h3 id="Exceptions">Exceptions</h3>
<dl>
<dt><code>SecurityError</code></dt>
<dd>The user agent blocked registration of the protocol handler. This might happen if an invalid scheme is specified, such as "http", which cannot be registered for obvious security reasons.</dd>
<dt><code>SyntaxError</code></dt>
<dd>The "%s" string is missing from the specified protocol handler URL.</dd>
</dl>
<h2 id="Permitted_schemes">Permitted schemes</h2>
<p>For security reasons, <code>registerProtocolHandler()</code> has restrictions on which schemes may be registered. A custom scheme may be registered as long as the scheme's name begins with "web+", is at least five characters long (including the "web+" prefix), and has only lower-case ASCII letters in its name. For example, "web+burger", as shown in the {{anch("Example")}} below.</p>
<p>Otherwise, the scheme must be one of the schemes on the whitelist below:</p>
<div class="threecolumns">
<ul>
<li><code>bitcoin</code></li>
<li><code>geo</code></li>
<li><code>im</code></li>
<li><code>irc</code></li>
<li><code>ircs</code></li>
<li><code>magnet</code></li>
<li><code>mailto</code></li>
<li><code>mms</code></li>
<li><code>news</code></li>
<li><code>nntp</code></li>
<li><code>sip</code></li>
<li><code>sms</code></li>
<li><code>smsto</code></li>
<li><code>ssh</code></li>
<li><code>tel</code></li>
<li><code>urn</code></li>
<li><code>webcal</code></li>
<li><code>wtai</code></li>
<li><code>xmpp</code></li>
</ul>
</div>
<h2 id="Example">Example</h2>
<p>If your web application is located at <code>http://www.google.co.uk</code>, you can register a protocol handler for it to handle "web+burger" links like this:</p>
<pre class="brush: js">navigator.registerProtocolHandler("web+burger",
"https://www.google.co.uk/?uri=%s",
"Burger handler");
</pre>
<p>This creates a handler that allows <code>web+burger://</code> links to direct the user to your web application, inserting the burger information specified in the link into the URL. Recall that this script must be run from the same domain (so any page location at <code>google.co.uk</code>) and the second argument passed must be of <code>http</code> or <code>https</code> scheme (in this example it is <code>https</code>) .</p>
<p>The user will be notified that your code has asked to register the protocol handler, so that they can decide whether or not to permit it. See the screenshot below for an example.</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/9683/protocolregister.png"></p>
<div class="note">
<p>"<a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#Getting_most_recent_window">Register a webmail service as mailto handler</a>" shows how to do this from XPCOM scope.</p>
</div>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName('HTML WHATWG', 'webappapis.html#dom-navigator-registerprotocolhandler', 'registerProtocolHandler()')}}</td>
<td>{{Spec2('HTML WHATWG')}}</td>
<td>Initial definition</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
{{Compat("api.Navigator.registerProtocolHandler")}}
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web-based_protocol_handlers">Web-based protocol handlers</a></li>
<li><a href="/en-US/docs/Web/API/Navigator/registerContentHandler">Navigator.registerContentHandler()</a></li>
<li><a href="http://blog.mozilla.com/webdev/2010/07/26/registerprotocolhandler-enhancing-the-federated-web/">RegisterProtocolHandler Enhancing the Federated Web</a> at Mozilla Webdev</li>
<li><a href="https://html.spec.whatwg.org/multipage/system-state.html#custom-handlers">Web Application APIs - Custom scheme and content handlers</a></li>
<li><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#Getting_most_recent_window">Register a webmail service as mailto handler</a> shows how to do <code>registerProtocolHandler</code> from XPCOM scope.</li>
<li><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#registerProtocolHandler">XPCOM Interface Reference > nsIWebContentHandlerRegistrar > registerContentHandler</a> - This shows how to use this function XPCOM scope</li>
</ul>
|
