diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 6026075d4fa83c3..0585256c3a884a3 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -7372,7 +7372,7 @@ /en-US/docs/Vuletube-vue-typescript-threejs-nui-voice-opencvjs /en-US/docs/Games/ /en-US/docs/WOFF /en-US/docs/Web/CSS/CSS_fonts/WOFF /en-US/docs/We/API/RotationRate /en-US/docs/Web/API/DeviceMotionEvent/rotationRate -/en-US/docs/Web-based_protocol_handlers /en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers +/en-US/docs/Web-based_protocol_handlers /en-US/docs/Web/API/Navigator/registerProtocolHandler /en-US/docs/Web-related_technologies /en-US/docs/Related /en-US/docs/Web/API/AbortController/FetchController /en-US/docs/Web/API/AbortController/AbortController /en-US/docs/Web/API/AbortSignal/abort /en-US/docs/Web/API/AbortSignal/abort_static @@ -9103,6 +9103,7 @@ /en-US/docs/Web/API/Navigator/mediaDevices/enumerateDevices /en-US/docs/Web/API/MediaDevices/enumerateDevices /en-US/docs/Web/API/Navigator/mediaDevices/getUserMedia /en-US/docs/Web/API/MediaDevices/getUserMedia /en-US/docs/Web/API/Navigator/mozIsLocallyAvailable /en-US/docs/Web/API/Navigator +/en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers /en-US/docs/Web/API/Navigator/registerProtocolHandler /en-US/docs/Web/API/NavigatorConcurrentHardware /en-US/docs/Web/API/Navigator /en-US/docs/Web/API/NavigatorConcurrentHardware/hardwareConcurrency /en-US/docs/Web/API/Navigator/hardwareConcurrency /en-US/docs/Web/API/NavigatorGeolocation /en-US/docs/Web/API/Geolocation diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 01e506d3564ef80..945865fbf69ce82 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -48262,36 +48262,6 @@ "BenoitL" ] }, - "Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers": { - "modified": "2019-03-24T00:11:06.750Z", - "contributors": [ - "sundevour", - "chrisdavidmills", - "thgh", - "ObooChin", - "Jeremie", - "groovecoder", - "teoli", - "staktrace", - "ethertank", - "Skierpage", - "sebmozilla", - "Crash", - "tito", - "Brettz9", - "Chris Chittleborough", - "Sheppy", - "Dabear", - "Mgjbot", - "Varmaa", - "Potappo", - "Shamrin", - "Dmose", - "MarkFinkle", - "Mcaruso", - "Callek" - ] - }, "Web/API/Navigator/requestMediaKeySystemAccess": { "modified": "2020-10-15T21:34:19.510Z", "contributors": [ diff --git a/files/en-us/mozilla/firefox/releases/3/index.md b/files/en-us/mozilla/firefox/releases/3/index.md index 09a069199549494..da8ade4f7ee2957 100644 --- a/files/en-us/mozilla/firefox/releases/3/index.md +++ b/files/en-us/mozilla/firefox/releases/3/index.md @@ -16,7 +16,7 @@ If you're a developer trying to get a handle on all the new features in Firefox - : Provides information about changes you may need to make to your website or web application to take advantage of new features in Firefox 3. - [Online and offline events](/en-US/docs/Web/API/Navigator/onLine) - : Firefox 3 supports WHATWG online and offline events, which let applications and extensions detect whether or not there's an active Internet connection, as well as to detect when the connection goes up and down. -- [Web-based protocol handlers](/en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers) +- [Web-based protocol handlers](/en-US/docs/Web/API/Navigator/registerProtocolHandler) - : You can now register web applications as protocol handlers using the `navigator.registerProtocolHandler()` method. - [Drawing text using a canvas](/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text) - : You can now draw text in a canvas using a non-standardized API supported by Firefox 3. diff --git a/files/en-us/web/api/navigator/registerprotocolhandler/index.md b/files/en-us/web/api/navigator/registerprotocolhandler/index.md index 7e3b05f12b26a88..bd2fb61c5f6f36c 100644 --- a/files/en-us/web/api/navigator/registerprotocolhandler/index.md +++ b/files/en-us/web/api/navigator/registerprotocolhandler/index.md @@ -8,10 +8,16 @@ browser-compat: api.Navigator.registerProtocolHandler {{APIRef("HTML DOM")}}{{securecontext_header}} -The **{{domxref("Navigator")}}** method **`registerProtocolHandler()`** lets websites register their ability to open or handle particular URL schemes (aka protocols). +The **{{domxref("Navigator")}}** method **`registerProtocolHandler()`** lets websites register their ability to open or handle particular URL schemes (also known as protocols). For example, this API lets webmail sites open `mailto:` URLs, or VoIP sites open `tel:` URLs. +To register a protocol handler, a website calls `registerProtocolHandler()`, passing in the protocol to register and a template URL. + +When the user activates a link that uses the registered protocol, the browser will insert the [`href`](/en-US/docs/Web/HTML/Element/a#href) from the activated link into the URL template supplied during handler registration, and navigate the current page to the resulting URL. + +The browser may ask the user to confirm that they want the page to be allowed to handle the protocol, either when the protocol is registered or when the user activates the link. + ## Syntax ```js-nolint @@ -22,16 +28,49 @@ registerProtocolHandler(scheme, url) - `scheme` - - : A string containing the [permitted scheme](#permitted_schemes) for the protocol that the site wishes to handle. - For example, you can register to handle SMS text message links by passing the `"sms"` scheme. + - : A string containing the scheme for the protocol that the site wishes to handle. + + This may be a custom scheme, in which case the scheme's name: + + - Begins with `web+` + - Contains at least one letter after the `web+` prefix + - Contains only lowercase {{Glossary("ASCII")}} letters. + + Otherwise, the scheme must be one of the following: + + - `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` - : A string containing the URL of the handler. - **This URL must include `%s`**, as a placeholder that will be replaced with the [escaped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) URL to be handled. + This URL must include `%s`, as a placeholder that will be replaced with the [escaped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) URL to be handled. - > [!NOTE] - > The handler URL must use the `https` scheme. Older browsers also supported `http`. + The handler URL must use the `https` scheme, and must be of the same {{glossary("origin")}} as the webpage that is attemtping to register the handler. ### Return value @@ -46,71 +85,29 @@ None ({{jsxref("undefined")}}). - The registered scheme (protocol) is invalid, such as a scheme the browser handles itself (`https:`, `about:`, etc.) - The handler URL's {{Glossary("origin")}} does not match the origin of the page calling this API. - - The browser requires that this function is called from a secure context. - - The browser requires that the handler's URL be over HTTPS. + - The handler's URL's scheme is not `https`. - `SyntaxError` {{domxref("DOMException")}} - : The `%s` placeholder is missing from the handler URL. -## Permitted schemes - -For security reasons, `registerProtocolHandler()` restricts which schemes can be registered. - -A **custom scheme** may be registered as long as: - -- The custom scheme's name begins with `web+` -- The custom scheme's name includes at least 1 letter after the `web+` prefix -- The custom scheme has only lowercase {{Glossary("ASCII")}} letters in its name. - -For example, `web+burger`, as shown in the [Example](#examples) below. - -Otherwise, the scheme must be one of the following: - -- `bitcoin` -- `ftp` -- `ftps` -- `geo` -- `im` -- `irc` -- `ircs` -- `magnet` -- `mailto` -- `matrix` -- `mms` -- `news` -- `nntp` -- `openpgp4fpr` -- `sftp` -- `sip` -- `sms` -- `smsto` -- `ssh` -- `tel` -- `urn` -- `webcal` -- `wtai` -- `xmpp` - - - ## Examples -If your site is `burgers.example.com`, you can register a protocol handler for it to handle `web+burger:` links, like so: +In this example, a page served from `https://burgers.example.org/` contains a link like this: + +```html +cheeseburger +``` + +It registers the `web+burger` with code like this: ```js navigator.registerProtocolHandler( "web+burger", - "https://burgers.example.com/?burger=%s", + "https://burgers.example.org/?burger=%s", ); ``` -This creates a handler that lets `web+burger:` links send the user to your site, inserting the accessed burger URL into the `%s` placeholder. - -This script must be run from the same origin as the handler URL (so any page at `https://burgers.example.com`), and the handler URL must be `http` or `https`. - -The user will be notified that your code asked to register the protocol handler, so that they can decide whether or not to allow it. See the screenshot below for an example on `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.](protocolregister.png) +If the registration was successful, then if the user activates the `web+burger` link, the browser will navigate to `https://burgers.example.org/?burger=web+burger:cheeseburger`. ## Specifications @@ -119,8 +116,3 @@ The user will be notified that your code asked to register the protocol handler, ## Browser compatibility {{Compat}} - -## See also - -- [Web-based protocol handlers](/en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers) -- [RegisterProtocolHandler Enhancing the Federated Web](https://blog.mozilla.org/webdev/2010/07/26/registerprotocolhandler-enhancing-the-federated-web/) (Mozilla Webdev) diff --git a/files/en-us/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.md b/files/en-us/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.md deleted file mode 100644 index 7405040b25f0854..000000000000000 --- a/files/en-us/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Web-based protocol handlers -slug: Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers -page-type: guide ---- - -{{APIRef("HTML DOM")}} - -## Background - -It's fairly common to find web pages link to resources using non-`http` protocols. An example is the `mailto:` protocol: - -```html -Web Master -``` - -Web authors can use a `mailto:` link when they want to provide a convenient way for users to send an email, directly from the webpage. When the link is activated, the browser should launch the default desktop application for handling email. You can think of this as a _desktop-based_ protocol handler. - -Web-based protocol handlers allow web-based applications to participate in the process too. This is becoming more important as more types of applications migrate to the web. In fact, there are many web-based email handling applications that could process a `mailto` link. - -## Registering - -Setting up a web application as a protocol handler is not a difficult process. Basically, the web application uses [`registerProtocolHandler()`](/en-US/docs/Web/API/Navigator/registerProtocolHandler) to register itself with the browser as a potential handler for a given protocol. For example: - -```js -navigator.registerProtocolHandler( - "web+burger", - "http://www.google.co.uk/?uri=%s", - "Burger handler", -); -``` - -Where the parameters are: - -- The protocol. -- The URL template, used as the handler. The "%s" is replaced with the `href` of the link and a GET is executed on the resultant URL. -- The user friendly name for the protocol handler. - -When a browser executes this code, it should let the user choose how to handle the protocol. The browser could prompt the user for registration immediately, or wait until the user clicks on a link that uses the protocol. Firefox displays a prompt in the notification bar area: - -![Screenshot of a prompt that reads: Add Burger handler (google.co.uk) as an application for burger links. An Add Application button is next to the text.](protocolregister.png) - -> [!NOTE] -> The URL template supplied when registering **must** be of the same domain as the webpage attempting to perform the registration or the registration will fail. For example, `http://example.com/homepage.html` can register a protocol handler for `http://example.com/handle_mailto/%s`, but not for `http://example.org/handle_mailto/%s`. - -### Example - -```html - - - - - - Web Protocol Handler Sample - Register - - - -

Web Protocol Handler Sample

-

- This web page will install a web protocol handler for the - web+burger: protocol. -

- - -``` - -## Activating - -Now, anytime the user activates a link that uses the registered protocol, the browser will route the action to the URL supplied when the web application registered. Firefox will, by default, prompt the user before handling off the action. - -### Example - -```html - - - - Web Protocol Handler Sample - Test - - -

Hey have you seen this before?

- - -``` - -## Handling - -The next phase is handling the action. The browser extracts the `href` from the activated link, combines it with the URL template supplied during handler registration and performs an HTTP GET on the URL. So, using the above examples, the browser would perform a GET on this URL: - -```url -http://www.google.co.uk/?uri=web+burger:cheeseburger -``` - -Server side code can extract the query string parameters and perform the desired action. - -> [!NOTE] -> The server side code is passed the **entire** contents of the `href`. This means the server side code will have to parse out the protocol from the data. - -### Example - -```php - - - - - - Web Protocol Handler Sample - - -

Web Protocol Handler Sample - Handler

-

This web page is called when handling a web+burger: protocol action. The data sent:

- - - -``` - -## References - -- [http://www.w3.org/TR/2011/WD-html5-20110525/timers.html#custom-handlers](https://www.w3.org/TR/2011/WD-html5-20110525/timers.html#custom-handlers) - -## See also - -- `nsIProtocolHandler` (XUL only) -- [RegisterProtocolHandler Enhancing the Federated Web](https://blog.mozilla.org/webdev/2010/07/26/registerprotocolhandler-enhancing-the-federated-web/) at Mozilla Webdev -- [Register a custom protocolHandler](https://web.dev/articles/registering-a-custom-protocol-handler) at web.dev. diff --git a/files/en-us/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/protocolregister.png b/files/en-us/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/protocolregister.png deleted file mode 100644 index 7bd7ac8717067fd..000000000000000 Binary files a/files/en-us/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/protocolregister.png and /dev/null differ diff --git a/files/en-us/web/html/element/iframe/index.md b/files/en-us/web/html/element/iframe/index.md index e2cdb16adf39656..2d79eb5b879624f 100644 --- a/files/en-us/web/html/element/iframe/index.md +++ b/files/en-us/web/html/element/iframe/index.md @@ -127,7 +127,7 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib - `allow-top-navigation-by-user-activation` - : Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture. - `allow-top-navigation-to-custom-protocols` - - : Allows navigations to non-`http` protocols built into browser or [registered by a website](/en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers). This feature is also activated by `allow-popups` or `allow-top-navigation` keyword. + - : Allows navigations to non-`http` protocols built into browser or [registered by a website](/en-US/docs/Web/API/Navigator/registerProtocolHandler). This feature is also activated by `allow-popups` or `allow-top-navigation` keyword. > [!NOTE] > diff --git a/files/en-us/web/http/headers/content-security-policy/sandbox/index.md b/files/en-us/web/http/headers/content-security-policy/sandbox/index.md index ed86fbbbfb01764..b8da5dc91b1f452 100644 --- a/files/en-us/web/http/headers/content-security-policy/sandbox/index.md +++ b/files/en-us/web/http/headers/content-security-policy/sandbox/index.md @@ -70,7 +70,7 @@ where `` can optionally be one of the following values: - `allow-top-navigation-by-user-activation` - : Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture. - `allow-top-navigation-to-custom-protocols` - - : Allows navigations to non-`http` protocols built into browser or [registered by a website](/en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers). This feature is also activated by `allow-popups` or `allow-top-navigation` keyword. + - : Allows navigations to non-`http` protocols built into browser or [registered by a website](/en-US/docs/Web/API/Navigator/registerProtocolHandler). This feature is also activated by `allow-popups` or `allow-top-navigation` keyword. > [!NOTE] > The `allow-top-navigation` and related values only make sense for embedded documents (such as child iframes). For standalone documents, these values have no effect, as the top-level browsing context is the document itself.