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

Jump to bottom

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 31 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 @@ -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 @@ -1006,6 +1008,109 @@ <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=].
</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>
</ol>
</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>
<ul>
diekus marked this conversation as resolved.
Show resolved Hide resolved
<li>[=list/For each=] |processedProtocolHandlers|, [=register a
Copy link
Collaborator

Choose a reason for hiding this comment

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

I don't think this can appear here without context (not part of any algorithm). It doesn't say when it should happen, or what the requirement level is (I think it should be a SHOULD; without that it implies MUST).

At a minimum, this should be in an algorithm "To register the protocol handlers for a processed manifest manifest", then you can properly index into that manifest in the for loop, e.g. "For each protocolHandler of manifest["protocol_handlers"]".

Ideally, this would be called from an algorithm that's invoked at install time, but I don't see one of those. So maybe just add a note to the "Installable web applications" section to say the user agent MAY [=register the protocol handlers=]".

Copy link
Member Author

Choose a reason for hiding this comment

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

I have added the SHOULD requirement level for the registration and fixed the loose ul element that made it appear as orphan. I have also added a note to the installable web applications section indicating that a protocol handler may be installed.

protocol handler=].
</li>
<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>
</ul>
</section>
<section>
<h2>
Manifest life-cycle
Expand Down Expand Up @@ -1104,6 +1209,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 @@ -1762,6 +1870,96 @@ <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>
<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
Security and privacy section of
{{NavigatorContentUtils/registerProtocolHandler()}}.
</p>
<p>
The user agent MUST ask for permission when using a protocol handler
for the first time. This feature requires user interaction and a
Copy link
Collaborator

Choose a reason for hiding this comment

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

I don't understand this second sentence. Are you trying to write a normative requirement that registration requires user interaction? Are you justifying the previous MUST requirement? Please rephrase this.

script cannot communicate with another application on its own.
</p>
</section>
</section>
<section>
<h2>
External application resource
Expand Down Expand Up @@ -2403,6 +2601,7 @@ <h4>
</p>
<pre class="example js" title=
"Accessing 'display-mode' media feature with script">

diekus marked this conversation as resolved.
Show resolved Hide resolved
const standalone = matchMedia( '(display-mode: standalone)' );

standalone.onchange = (e) =&gt; {
Expand Down Expand Up @@ -2935,7 +3134,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