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
Open

Adding protocol handlers #972

Changes from 2 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
206 changes: 206 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,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 @@ -1004,6 +1006,116 @@ <h3>
conventions or limitations of the host operating system.
</p>
</section>
<section>
<h3>
`protocol_handlers` member
</h3>
<p>
The [=manifest's=] <code><dfn data-export="" data-dfn-for=
"manifest">protocol_handlers</dfn></code> member is an <a>array</a>
diekus marked this conversation as resolved.
Show resolved Hide resolved
of <a>ProtocolHandlerItem</a>s that allows a web application to
handle URL protocols.
</p>
<p class="note">
diekus marked this conversation as resolved.
Show resolved Hide resolved
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>
The steps for <dfn>processing the <code>protocol_handlers</code>
diekus marked this conversation as resolved.
Show resolved Hide resolved
member</dfn> are given by the following algorithm. The algorithm
takes a <a data-cite=
"WEBIDL#sequence-type">sequence</a>&lt;<a>ProtocolHandlerItem</a>&gt;
diekus marked this conversation as resolved.
Show resolved Hide resolved
<var>protocol_handlers</var> and a <a>URL</a> <var>manifest
URL</var>. This algorithm returns a <a data-cite=
diekus marked this conversation as resolved.
Show resolved Hide resolved
"WEBIDL#sequence-type">sequence</a>&lt;<a>ProtocolHandlerItem</a>&gt;.
</p>
<ol>
<li>Let <var>processedProtocolHandlers</var> be a new Array object
diekus marked this conversation as resolved.
Show resolved Hide resolved
created as if by the expression [].
</li>
diekus marked this conversation as resolved.
Show resolved Hide resolved
<li>For each <var>protocol_handler</var> (<a>ProtocolHandlerItem</a>)
diekus marked this conversation as resolved.
Show resolved Hide resolved
in the sequence:
<ol>
<li>If <var>protocol_handler</var>["protocol"] or
diekus marked this conversation as resolved.
Show resolved Hide resolved
<var>protocol_handler</var>["url"] are undefined, return failure
diekus marked this conversation as resolved.
Show resolved Hide resolved
and [=iteration/continue=].
</li>
<li>Set <var>protocol_handler</var>["url"] to the result of [=URL
Parser|parsing=] <var>protocol_handler</var>["url"] using
<var>manifest URL</var> as the base URL. If the result is
failure, [=iteration/continue=].
</li>
<li>If <var>protocol_handler</var>["url"] is not
[=manifest/within scope=] of <var>manifest URL</var>, return
failure and [=iteration/continue=].
</li>
<li>If <var>protocol_handler</var>["url"] already exists in <var>
diekus marked this conversation as resolved.
Show resolved Hide resolved
processedProtocolHandlers</var>, return failure and
[=iteration/continue=].
</li>
<li>
<a>Append</a> <var>protocol_handler</var> to
diekus marked this conversation as resolved.
Show resolved Hide resolved
diekus marked this conversation as resolved.
Show resolved Hide resolved
<var>processedProtocolHandlers</var>.
</li>
</ol>
</li>
<li>Return <var>processedProtocolHandlers</var>.
</li>
</ol>
<p>
To process the the <var>processedProtocolHandlers</var> the user
agent SHOULD [=register a handler=] per item defined in the
[=sequence=].
</p>
<p>
A user agent SHOULD ask users for permission before registering a
<a>ProtocolHandlerItem</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>ProtocolHandlerItem</a>
<var>protocol_handlers</var> presented in order to remain consistent
with the conventions or limitations of the host operating system.
</p>
<div class="example">
diekus marked this conversation as resolved.
Show resolved Hide resolved
<p>
In the following example, the developer has included two
<a>ProtocolHandlerItem</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
safelist.
diekus marked this conversation as resolved.
Show resolved Hide resolved
</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>
</div>
diekus marked this conversation as resolved.
Show resolved Hide resolved
</section>
<section>
<h2>
Manifest life-cycle
Expand Down Expand Up @@ -1755,6 +1867,100 @@ <h2>
</ol>
</section>
</section>
<section>
<h2>
ProtocolHandler items
</h2>
<p>
Each <dfn>ProtocolHandlerItem</dfn> is an [=object=] that represents
diekus marked this conversation as resolved.
Show resolved Hide resolved
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
diekus marked this conversation as resolved.
Show resolved Hide resolved
launch</a>.
</p>
<p class="note">
diekus marked this conversation as resolved.
Show resolved Hide resolved
[[HTML]]'s <code>registerProtocolHandler</code> method allows web sites
diekus marked this conversation as resolved.
Show resolved Hide resolved
to register themselves as possible handlers for particular protocols.
What constitutes valid <code>protocol</code> and <code>url</code>
values for <a>ProtocolHandlerItem</a>s is defined in that API. Also
note that the [[HTML]] API uses <a href=
"https://url.spec.whatwg.org/#concept-url-scheme"><code>scheme</code></a>
diekus marked this conversation as resolved.
Show resolved Hide resolved
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>ProtocolHandlerItem</a> is a
<a>string</a> that represents the protocol to be handled, such as
"mailto" or "web+auth".
diekus marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
The <a>protocol</a> member of a <a>ProtocolHandlerItem</a> is
equivalent to {{NavigatorContentUtils/registerProtocolHandler()}}'s
<a href="https://url.spec.whatwg.org/#concept-url-scheme">scheme</a>
argument defined in [[HTML]].
diekus marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>
<section>
<h3>
`url` member
</h3>
<p>
The <dfn>url</dfn> member of a <a>ProtocolHandlerItem</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>ProtocolHandlerItem</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>ProtocolHandlerItem</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>
<h3>
Privacy and Security considerations
Copy link
Collaborator

Choose a reason for hiding this comment

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

I'm not sure this should go here. There's a main P&S section at the end of the document that collects all of these (this would be the only section to have it's own P&S subsection, other than Installable Web Apps, and that is probably a mistake too -- note that it is duplicated text from the end of the document).

However, I think P&S should only have non-normative discussion; a MUST requirement shouldn't be in it. So I would move this MUST requirement above to Handling a protocol launch. Then explain why it is so in the P&S section.

</h3>
<p>
Privacy concerns for custom scheme handling are detailed in the
<a href=
"https://html.spec.whatwg.org/multipage/system-state.html#security-and-privacy">
diekus marked this conversation as resolved.
Show resolved Hide resolved
Security and privacy section</a> of
{{NavigatorContentUtils/registerProtocolHandler()}}.
</p>
<div class="note">
<p>
The user agent MUST ask for permission when using a protocol
handler for the first time. This feature requires user interaction
and a script cannot communicate with another application on its
own.
</p>
</div>
diekus marked this conversation as resolved.
Show resolved Hide resolved
</section>
</section>
<section>
<h2>
External application resource
Expand Down