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

Add protocol handlers to the explainer and spec #863

Closed
wants to merge 1 commit into from
Closed

Add protocol handlers to the explainer and spec #863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 20 additions & 0 deletions explainer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,26 @@ Numerous operating systems grant native applications the ability to add menu ite
]
```

## Adding protocol handlers
Native applications often register themselves as protocol handlers to increase discoverability and usage. For web applications, you can define a set of protocol handlers to be exposed when the app is installed. Each protocol handler item must have the protocol to be handled and the URL used to handle the protocol links.

```JSON
"protocol_handlers": [
{
"protocol": "mailto",
"url": "/mailto?%s",
},
{
"protocol": "sms",
"url": "/sms?number=%s",
},
{
"protocol": "web+msg",
"url": "/msg?handler=%s",
}
]
```

## How can I detect if the user "installed" my app?
The spec provides a way for you to detect when the user installs your apps by registering for "appinstalled" events.

Expand Down
195 changes: 195 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1171,6 +1171,11 @@ <h3>
running <a>processing the <code>shortcuts</code> member</a> given
<var>manifest</var>["<a>shortcuts</a>"] and <var>manifest URL</var>.
</li>
<li>Set <var>manifest</var>["<a>protocol_handlers</a>"] to the result
of running <a>processing the <code>protocol_handlers</code>
member</a> given <var>manifest</var>["<a>protocol_handlers</a>"] and
<var>manifest URL</var>.
</li>
<li>
<a>Extension point</a>: process any proprietary and/or other
supported members at this point in the algorithm.
Expand Down Expand Up @@ -1247,6 +1252,7 @@ <h2>
sequence&lt;ExternalApplicationResource&gt; related_applications;
boolean prefer_related_applications = "false";
sequence&lt;ShortcutItem&gt; shortcuts;
sequence&lt;ProtocolHandlerItem&gt; protocol_handlers;
};
</pre>
<p>
Expand Down Expand Up @@ -2080,6 +2086,111 @@ <h3>
</pre>
</div>
</section>
<section>
<h3>
<code>protocol_handlers</code> member
</h3>
<p>
The <dfn>protocol_handlers</dfn> member is an <a>array</a> of
<a>ProtocolHandlerItem</a>s that allows a web application to handle
URL protocols.
</p>
<p class="note">
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>
Comment on lines +2098 to +2107
Copy link
Member

Choose a reason for hiding this comment

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

This doesn't sound amazing from a security perspective. I'm assuming all cross app communication is user mediated?

<p>
The steps for <dfn>processing the <code>protocol_handlers</code>
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;
<var>protocol_handlers</var> and a <a>URL</a> <var>manifest
URL</var>. This algorithm returns a <a data-cite=
"WEBIDL#sequence-type">sequence</a>&lt;<a>ProtocolHandlerItem</a>&gt;.
</p>
<ol>
<li>Let <var>processedProtocolHandlers</var> be a new Array object
Copy link
Member

Choose a reason for hiding this comment

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

probably make this a set, and then you can later check for duplicates with [=list/contains=].

created as if by the expression [].
</li>
<li>For each <var>protocol_handler</var> (<a>ProtocolHandlerItem</a>)
in the sequence:
<ol>
<li>If <var>protocol_handler</var>["protocol"] or
<var>protocol_handler</var>["url"] are undefined, <a>issue a
developer warning</a> and [=iteration/continue=].
</li>
<li>Set <var>protocol_handler</var>["url"] to the result of [=URL
Copy link
Member

Choose a reason for hiding this comment

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

It's best to create a new variable here to store the newly parsed URL.

Parser|parsing=] <var>protocol_handler</var>["url"] using
<var>manifest URL</var> as the base URL. If the result is
failure, <a>issue a developer warning</a> and
[=iteration/continue=].
</li>
<li>If <var>protocol_handler</var>["url"] is not <a>within
scope</a> of <var>manifest URL</var>, <a>issue a developer
warning</a> and [=iteration/continue=].
Comment on lines +2134 to +2136
Copy link
Member

Choose a reason for hiding this comment

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

I think we have a nice shorthand for this:

Suggested change
<li>If <var>protocol_handler</var>["url"] is not <a>within
scope</a> of <var>manifest URL</var>, <a>issue a developer
warning</a> and [=iteration/continue=].
<li>If <var>protocol_handler</var>["url"] is not [=manifest/within
scope=], [=iteration/continue=].

</li>
<li>If <var>protocol_handler</var>["url"] already exists in <var>
processedProtocolHandlers</var>, <a>issue a developer
warning</a> and [=iteration/continue=].
</li>
<li>
<a>Append</a> <var>protocol_handler</var> to
<var>processedProtocolHandlers</var>.
</li>
</ol>
</li>
<li>Return <var>processedProtocolHandlers</var>.
</li>
</ol>
<p>
A user agent SHOULD ask users for permission before registering a
<a>ProtocolHandlerItem</a> <var>protocol_handler</var> 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_handler</var> presented in order to remain consistent
with the conventions or limitations of the host operating system.
</p>
<div class="example">
<p>
In the following example, the developer has included two
<a>ProtocolHandlerItem</a> <var>protocol_handler</var>. 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.
</li>
</ul>
<pre class="example json">
{
"protocol_handlers": [
{
"protocol": "web+music",
"url": "/play?songId=%s"
},
{
"protocol": "store",
"url": "/buy?songId=%s"
}
]
}
</pre>
</div>
</section>
</section>
<section>
<h2>
Expand Down Expand Up @@ -2708,6 +2819,90 @@ <h3>
</ol>
</section>
</section>
<section>
<h2>
<dfn>ProtocolHandlerItem</dfn> and its members
</h2>
<pre class="idl">
dictionary ProtocolHandlerItem {
required DOMString protocol;
required USVString url;
};
</pre>
<p>
Each <a>ProtocolHandlerItem</a> represents a protocol that the web
application wants to handle and the corresponding URL that should
handle the request. 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">
[[HTML]]'s <code>registerProtocolHandler</code> method 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>ProtocolHandlerItem</a>s is defined in that API. Also
note that the [[HTML]] API uses <code>scheme</code> where we use
<code>protocol</code> but the same restrictions apply.
</p>
<section data-dfn-for="ProtocolHandlerItem" data-link-for=
"ProtocolHandlerItem">
<h3>
<code>protocol</code> 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".
</p>
<p>
The <a>protocol</a> member of a <a>ProtocolHandlerItem</a> is
equivalent to <code>registerProtocolHandler</code>'s
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
equivalent to <code>registerProtocolHandler</code>'s
equivalent to {{NavigatorContentUtils/registerProtocolHandler()}}'s

<code>scheme</code> argument defined in [[HTML]], and is processed in
the same manner.
Comment on lines +2861 to +2862
Copy link
Member

Choose a reason for hiding this comment

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

this is probably not sufficient... here we want to make sure the HTML folks export something out from there spec that we can call into to process these.

</p>
</section>
<section data-dfn-for="ProtocolHandlerItem" data-link-for=
"ProtocolHandlerItem">
<h3>
<code>url</code> member
</h3>
<p>
The <dfn>url</dfn> member of a <a>ProtocolHandlerItem</a> is the
<a>URL</a> <a data-lt="within scope of a manifest">within the
Copy link
Member

Choose a reason for hiding this comment

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

Please use "manifest scope" here, otherwise it might get confusing as "application scope" is not a defined thing.

Copy link
Member

Choose a reason for hiding this comment

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

updated to "manifest scope".

application's scope</a> that opens when the associated protocol is
activated.
</p>
<p>
The <a>url</a> member of a <a>ProtocolHandlerItem</a> is equivalent
Copy link
Member

Choose a reason for hiding this comment

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

as above... this is probably not ideal (as per the TAG comments about layering). We own our own definitions of these things, and then we make them work with the underlying model of HTML.

to <code>registerProtocolHandler</code>'s <code>url</code> argument
defined in [[HTML]], and is processed in the same manner.
</p>
</section>
<section>
<h3>
<dfn>Handling a protocol launch</dfn>
</h3>
<p>
When a <a>ProtocolHandlerItem</a> <var>protocol_handler</var> having
<a>WebAppManifest</a> <var>manifest</var> is invoked, run the
following steps:
</p>
<ol>
<li>Let <var>url</var> be <var>protocol_handler.url</var>.
Copy link
Member

Choose a reason for hiding this comment

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

The algorithm should operate on the document's "processed manifest" instead.

</li>
<li>Replace the first occurrence of the exact literal string "%s" in
Copy link
Member

Choose a reason for hiding this comment

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

Ok, this bit probably needs really precise processing as a simple replace here might end up with security issues. If anything, we want to do whatever HTML does ... or maybe whatever Web Share Target does.

cc @mgiuca

<var>url</var> with an escaped version of the absolute URL.
</li>
<li>Let <var>browsing context</var> be the result of creating a new
<a>top-level browsing context</a>.
</li>
<li>
<a>Navigate</a> <var>browsing context</var> to <var>url</var>.
</li>
</ol>
</section>
</section>
<section>
<h2>
Multi-purpose members
Expand Down