Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding protocol handlers #972

Open
wants to merge 34 commits into
base: main
Choose a base branch
from
+201 −1
Open

Adding protocol handlers #972

Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
999f9a9
adds protocol_handlers member
diekus Apr 15, 2021
da610bd
Update index.mhtml (adds protocol_handlers)
diekus Apr 26, 2021
8664c01
update index.htmlo
diekus Apr 26, 2021
228e2e6
Update index.html
diekus Apr 26, 2021
e1b678f
Update index.html
diekus May 7, 2021
81bdeda
Update index.html
diekus May 7, 2021
2c023ef
Update index.html
diekus May 7, 2021
2ace6ea
Merge branch 'gh-pages' into adding-protocol-handlers
aarongustafson May 13, 2021
61780a4
updates to protocol_handlers
diekus May 17, 2021
8b698d5
Merge branch 'adding-protocol-handlers' of https://github.com/w3c/man…
diekus May 17, 2021
9314353
Update index.html
diekus May 17, 2021
264ab23
Update index.html
diekus May 18, 2021
b011275
Update index.html
diekus May 18, 2021
1dcffe3
Update index.html
diekus May 18, 2021
0d4f273
Update index.html
diekus May 24, 2021
f0945d4
Update index.html
diekus May 24, 2021
003c2b1
Update index.html
diekus May 24, 2021
34d479b
Update index.html
diekus May 24, 2021
d440080
Update index.html
diekus May 24, 2021
94811fb
Update index.html
diekus May 24, 2021
f145884
Update index.html
diekus May 25, 2021
18c9046
Update index.html
diekus Jun 7, 2021
ea5cb7b
Merge branch 'gh-pages' into adding-protocol-handlers
diekus Jun 7, 2021
2573589
Update index.html
diekus Jun 15, 2021
3998cfa
Merge branch 'gh-pages' into adding-protocol-handlers
marcoscaceres Jun 23, 2021
8308ae2
Merge branch 'gh-pages' into adding-protocol-handlers
marcoscaceres Jun 30, 2021
2b4ba13
Run tidy
diekus Jul 5, 2021
c034185
run tidy
diekus Jul 5, 2021
40f8a13
Merge branch 'gh-pages' into adding-protocol-handlers
diekus Jul 12, 2021
73f3812
Update index.html
diekus Jul 13, 2021
ec620b6
Merge branch 'gh-pages' into adding-protocol-handlers
marcoscaceres Jul 20, 2021
6de904e
Fixes index.html
diekus Aug 2, 2021
ee2674a
Merge branch 'gh-pages' into adding-protocol-handlers
diekus Aug 2, 2021
b8c938a
Merge branch 'main' into adding-protocol-handlers
marcoscaceres Apr 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 201 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,8 @@ <h2>
</li>
<li>[=manifest/prefer_related_applications=]
</li>
<li>[=manifest/protocol_handlers=]
</li>
<li>[=manifest/related_applications=]
</li>
<li>[=manifest/scope=]
Expand Down Expand Up @@ -1216,6 +1218,111 @@ <h3>
conventions or limitations of the host operating system.
</p>
</section>
<section>
<h3>
`protocol_handlers` member
</h3>
<p>
The [=manifest's=] <code><dfn data-dfn-for=
"manifest">protocol_handlers</dfn></code> member is an <a>array</a>
of <a>protocol handler description</a>s that allows a web application
to handle URL protocols.
</p>
<p class="example">
Protocol handlers could, for instance, be used for web app
communication where one app directly invokes another and passes data
via custom protocol links.
</p>
<p>
How protocol handlers are presented, and how many of them are shown
to the user, is at the discretion of the user agent and/or operating
system.
</p>
<p>
To <dfn>process the `protocol_handlers` member</dfn>, given
[=object=] |json:JSON|, |manifest:ordered map|, and |manifest
URL:URL|:
</p>
<ol>
<li>Let <var>processedProtocolHandlers</var> be a new [=list=] of
|json:JSON|["<var>protocol_handlers</var>"].
</li>
<li>Set manifest["<var>protocol_handlers</var>"] to
<var>processedProtocolHandlers</var>.
</li>
diekus marked this conversation as resolved.
Show resolved Hide resolved
<li>[=list/For each=] <var>protocol_handler</var> (<a>protocol
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be consistent with variable naming. Looks like we're using camelCase, so protocolHandler not protocol_handler.

Question for @kenchris : did this change recently? I'm looking at the shortcuts algorithm above which uses variables like processedShortcuts. I swear we used to use variable names with spaces in them, not camelCaseVariableNames.

handler description</a>):
diekus marked this conversation as resolved.
Show resolved Hide resolved
<ol>
<li>If |protocol_handler|["protocol"] or
<var>protocol_handler</var>["url"] is undefined,
[=iteration/continue=].
</li>
<li>Let (<dfn>normalizedProtocol</dfn>, <dfn>normalizedUrl</dfn>)
be the result of running [=normalize protocol handler
parameters=] with <var>protocol_handler</var>["protocol"], <var>
protocol_handler</var>["url"] using <var>manifest URL</var> as
the base URL, and [=this=]'s relevant [=environment settings
object=]. If the result is failure, [=iteration/continue=].
</li>
<li>If [=normalizedUrl=] is not [=manifest/within scope=] of
<var>manifest URL</var>, [=iteration/continue=].
</li>
<li>If [=normalizedUrl=] already exists in
<var>processedProtocolHandlers</var>, [=iteration/continue=].
</li>
<li>[=List/Append=] |protocol_handler| to
<var>processedProtocolHandlers</var>.
</li>
</ol>
</li>
<li>[=list/For each=] |processedProtocolHandlers|, the user agent
SHOULD [=register a protocol handler=].
</li>
</ol>
<p>
A user agent SHOULD ask users for permission before registering a
<a>protocol handler description</a> <var>protocol_handler</var>s as
the default handler for a protocol with the host operating system. A
user agent MAY truncate the list of <a>protocol handler
description</a> <var>protocol_handlers</var> presented in order to
remain consistent with the conventions or limitations of the host
operating system.
</p>
<aside class="example">
<p>
In the following example, the developer has included two
<a>protocol handler description</a> <var>protocol_handler</var>s.
Assuming the the manifest's URL is
<samp>https://example.com/manifest.webmanifest</samp>:
</p>
<ul>
<li>The first protocol handler would register to handle "web+music"
URLs (e.g.: web+music://#1234). When activated, the user agent
would instantiate a new <a>top-level browsing context</a> and
navigate to
<samp>https://example.com/play?songId=web+music://%231234</samp>.
</li>
<li>The second protocol handler would be ignored, as the protocol
provided does not start with "web+" and is not part of the
[=safelisted schemes=].
</li>
</ul>
<pre class="example json">
{
"protocol_handlers": [
{
"protocol": "web+music",
"url": "/play?songId=%s"
},
{
"protocol": "store",
"url": "/buy?songId=%s"
marcoscaceres marked this conversation as resolved.
Show resolved Hide resolved
}
]
}
</pre>
</aside>
</section>
<section>
<h2>
Manifest life-cycle
Expand Down Expand Up @@ -1314,6 +1421,9 @@ <h3>
<li>[=Process the `orientation` member=] passing |json|,
|manifest|.
</li>
<li>[=Process the `protocol_handlers` member=] passing |json|,
|manifest|, and |manifest URL|.
</li>
<li>[=Process the `related_applications` member=] passing |json|
and |manifest|.
</li>
Expand Down Expand Up @@ -2029,6 +2139,81 @@ <h2>
</ol>
</section>
</section>
<section>
<h2>
ProtocolHandler items
</h2>
<p>
Each <dfn>protocol handler description</dfn> is an [=object=] that
represents a protocol that the web application wants to handle. It has
the following members:
</p>
<ul>
<li>[=`protocol`=]
</li>
<li>[=`url`=]
</li>
</ul>
<p>
A user agent SHOULD use these values to register the web application as
a handler with the operating system. When the user activates a protocol
handler URL, the user agent SHOULD run <a>handling a protocol
launch</a>.
</p>
<p class="note">
diekus marked this conversation as resolved.
Show resolved Hide resolved
[[HTML]]'s {{NavigatorContentUtils/registerProtocolHandler()}} allows
web sites to register themselves as possible handlers for particular
protocols. What constitutes valid <code>protocol</code> and
<code>url</code> values for <a>protocol handler description</a>s is
defined in that API. Also note that the [[HTML]] API uses
[=url/scheme=] where we use <code>protocol</code> but the same
restrictions apply.
</p>
<section>
<h3>
`protocol` member
</h3>
<p>
The <dfn>protocol</dfn> member of a <a>protocol handler
description</a> is a <a>string</a> that represents the protocol to be
handled, such as `mailto` or `web+auth`.
</p>
<p>
The <a>protocol</a> member of a <a>protocol handler description</a>
is equivalent to
{{NavigatorContentUtils/registerProtocolHandler()}}'s |scheme|
argument defined in [[HTML]].
</p>
</section>
<section>
<h3>
`url` member
</h3>
<p>
The <dfn>url</dfn> member of a <a>protocol handler description</a> is
the <a>URL</a> [=manifest/within scope=] of the application that
opens when the associated protocol is activated.
</p>
<p>
The <a>url</a> member of a <a>protocol handler description</a> is
equivalent to {{NavigatorContentUtils/registerProtocolHandler()}}'s
<code>url</code> argument defined in [[HTML]].
</p>
</section>
<section>
<h3>
<dfn>Handling a protocol launch</dfn>
</h3>
<p>
When a <a>protocol handler description</a>
<var>protocol_handler</var> having [=manifest=] <var>manifest</var>
is invoked, it goes through the same steps used to [=invoke a
protocol handler=] defined in [=HTML=], where the user agent SHOULD
navigate to [=url=] and the appropriate browsing context is set to a
new top level browsing context.
</p>
</section>
</section>
<section>
<h2>
External application resource
Expand Down Expand Up @@ -2205,6 +2390,12 @@ <h2>
could <a>install</a> the web application into a list of bookmarks
within the user agent itself.
</p>
<div class="note">
<p>
When a web application is installed, a user agent MAY [=register a
protocol handler=].
</p>
</div>
<section>
<h3>
Application's name
Expand Down Expand Up @@ -2701,6 +2892,14 @@ <h2>
[[MEDIAQUERIES-5]], through which a script can know the display mode of
a web application.
</p>
<p>
Privacy concerns for custom scheme handling are detailed in the
Security and privacy section of
{{NavigatorContentUtils/registerProtocolHandler()}}. Before invoking a
protocol handler for the first time, the user agent prompts to request
for permission, there is no communication with another application
beforehand.
</p>
</section>
<section class="appendix">
<h2>
Expand Down Expand Up @@ -3133,7 +3332,8 @@ <h2>
Click to view schema.
</summary>
<pre class="json" data-include=
"https://json.schemastore.org/web-manifest"></pre>
"https://json.schemastore.org/web-manifest">
</pre>
</details>
</aside>
</section>
Expand Down