diff --git a/explainer.md b/explainer.md index 106b4c838..a6bd10e1e 100644 --- a/explainer.md +++ b/explainer.md @@ -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. diff --git a/index.html b/index.html index a9294c1a3..4e9e36924 100644 --- a/index.html +++ b/index.html @@ -1171,6 +1171,11 @@

running processing the shortcuts member given manifest["shortcuts"] and manifest URL. +
  • Set manifest["protocol_handlers"] to the result + of running processing the protocol_handlers + member given manifest["protocol_handlers"] and + manifest URL. +
  • Extension point: process any proprietary and/or other supported members at this point in the algorithm. @@ -1247,6 +1252,7 @@

    sequence<ExternalApplicationResource> related_applications; boolean prefer_related_applications = "false"; sequence<ShortcutItem> shortcuts; + sequence<ProtocolHandlerItem> protocol_handlers; };

    @@ -2080,6 +2086,111 @@

    +
    +

    + protocol_handlers member +

    +

    + The protocol_handlers member is an array of + ProtocolHandlerItems that allows a web application to handle + URL protocols. +

    +

    + Protocol handlers could, for instance, be used for web app + communication where one app directly invokes another and passes data + via custom protocol links. +

    +

    + 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. +

    +

    + The steps for processing the protocol_handlers + member are given by the following algorithm. The algorithm + takes a sequence<ProtocolHandlerItem> + protocol_handlers and a URL manifest + URL. This algorithm returns a sequence<ProtocolHandlerItem>. +

    +
      +
    1. Let processedProtocolHandlers be a new Array object + created as if by the expression []. +
      2. +
    2. For each protocol_handler (ProtocolHandlerItem) + in the sequence: +
        +
      1. If protocol_handler["protocol"] or + protocol_handler["url"] are undefined, issue a + developer warning and [=iteration/continue=]. +
        2. +
      2. Set protocol_handler["url"] to the result of [=URL + Parser|parsing=] protocol_handler["url"] using + manifest URL as the base URL. If the result is + failure, issue a developer warning and + [=iteration/continue=]. +
        3. +
      3. If protocol_handler["url"] is not within + scope of manifest URL, issue a developer + warning and [=iteration/continue=]. +
        4. +
      4. If protocol_handler["url"] already exists in + processedProtocolHandlers, issue a developer + warning and [=iteration/continue=]. +
        5. +
      5. + Append protocol_handler to + processedProtocolHandlers. +
        6. +
      +
      3. +
    3. Return processedProtocolHandlers. +
      4. +
    +

    + A user agent SHOULD ask users for permission before registering a + ProtocolHandlerItem protocol_handler as the default + handler for a protocol with the host operating system. A user agent + MAY truncate the list of ProtocolHandlerItem + protocol_handler presented in order to remain consistent + with the conventions or limitations of the host operating system. +

    +
    +

    + In the following example, the developer has included two + ProtocolHandlerItem protocol_handler. Assuming + the the manifest's URL is + https://example.com/manifest.webmanifest: +

    +
      +
    • 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 top-level browsing context and + navigate to + https://example.com/play?songId=web+music://%231234. +
      • +
    • The second protocol handler would be ignored, as the protocol + provided does not start with "web+" and is not part of the + safelist. +
      • +
    + 
    +            {
+              "protocol_handlers": [
+                {
+                  "protocol": "web+music",
+                  "url": "/play?songId=%s"
+                },
+                {
+                  "protocol": "store",
+                  "url": "/buy?songId=%s"
+                }
+              ]
+            }
+
    +
    +

    @@ -2708,6 +2819,90 @@

    +
    +

    + ProtocolHandlerItem and its members +

    + 
    +        dictionary ProtocolHandlerItem {
+          required DOMString protocol;
+          required USVString url;
+        };
+
    +

    + Each ProtocolHandlerItem 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 + Handling a protocol launch. +

    +

    + [[HTML]]'s registerProtocolHandler method allows web sites + to register themselves as possible handlers for particular protocols. + What constitutes valid protocol and url + values for ProtocolHandlerItems is defined in that API. Also + note that the [[HTML]] API uses scheme where we use + protocol but the same restrictions apply. +

    +
    +

    + protocol member +

    +

    + The protocol member of a ProtocolHandlerItem is a + string that represents the protocol to be handled, such as + "mailto" or "web+auth". +

    +

    + The protocol member of a ProtocolHandlerItem is + equivalent to registerProtocolHandler's + scheme argument defined in [[HTML]], and is processed in + the same manner. +

    +
    +
    +

    + url member +

    +

    + The url member of a ProtocolHandlerItem is the + URL within the + application's scope that opens when the associated protocol is + activated. +

    +

    + The url member of a ProtocolHandlerItem is equivalent + to registerProtocolHandler's url argument + defined in [[HTML]], and is processed in the same manner. +

    +
    +
    +

    + Handling a protocol launch +

    +

    + When a ProtocolHandlerItem protocol_handler having + WebAppManifest manifest is invoked, run the + following steps: +

    +
      +
    1. Let url be protocol_handler.url. +
      2. +
    2. Replace the first occurrence of the exact literal string "%s" in + url with an escaped version of the absolute URL. +
      3. +
    3. Let browsing context be the result of creating a new + top-level browsing context. +
      4. +
    4. + Navigate browsing context to url. +
      5. +
    +
    +

    Multi-purpose members