diff --git a/index.html b/index.html index 16596d72..474e4625 100644 --- a/index.html +++ b/index.html @@ -187,6 +187,8 @@

  • [=manifest/prefer_related_applications=]
    • +
  • [=manifest/protocol_handlers=] +
  • [=manifest/related_applications=]
  • [=manifest/scope=] @@ -1216,6 +1218,111 @@

    conventions or limitations of the host operating system.

    +
    +

    + `protocol_handlers` member +

    +

    + The [=manifest's=] protocol_handlers member is an array + of protocol handler descriptions 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. +

    +

    + To process the `protocol_handlers` member, given + [=object=] |json:JSON|, |manifest:ordered map|, and |manifest + URL:URL|: +

    +
      +
    1. Let processedProtocolHandlers be a new [=list=] of + |json:JSON|["protocol_handlers"]. +
      2. +
    2. Set manifest["protocol_handlers"] to + processedProtocolHandlers. +
      3. +
    3. [=list/For each=] protocol_handler (protocol + handler description): +
        +
      1. If |protocol_handler|["protocol"] or + protocol_handler["url"] is undefined, + [=iteration/continue=]. +
        2. +
      2. Let (normalizedProtocol, normalizedUrl) + be the result of running [=normalize protocol handler + parameters=] with protocol_handler["protocol"], + protocol_handler["url"] using manifest URL as + the base URL, and [=this=]'s relevant [=environment settings + object=]. If the result is failure, [=iteration/continue=]. +
        3. +
      3. If [=normalizedUrl=] is not [=manifest/within scope=] of + manifest URL, [=iteration/continue=]. +
        4. +
      4. If [=normalizedUrl=] already exists in + processedProtocolHandlers, [=iteration/continue=]. +
        5. +
      5. [=List/Append=] |protocol_handler| to + processedProtocolHandlers. +
        6. +
      +
      4. +
    4. [=list/For each=] |processedProtocolHandlers|, the user agent + SHOULD [=register a protocol handler=]. +
      5. +
    +

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

    + +

    Manifest life-cycle @@ -1314,6 +1421,9 @@

  • [=Process the `orientation` member=] passing |json|, |manifest|.
    • +
  • [=Process the `protocol_handlers` member=] passing |json|, + |manifest|, and |manifest URL|. +
  • [=Process the `related_applications` member=] passing |json| and |manifest|.
    • @@ -2029,6 +2139,81 @@

    +
    +

    + ProtocolHandler items +

    +

    + Each protocol handler description is an [=object=] that + represents a protocol that the web application wants to handle. It has + the following members: +

    +
      +
    • [=`protocol`=] +
      • +
    • [=`url`=] +
      • +
    +

    + 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 {{NavigatorContentUtils/registerProtocolHandler()}} allows + web sites to register themselves as possible handlers for particular + protocols. What constitutes valid protocol and + url values for protocol handler descriptions is + defined in that API. Also note that the [[HTML]] API uses + [=url/scheme=] where we use protocol but the same + restrictions apply. +

    +
    +

    + `protocol` member +

    +

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

    +

    + The protocol member of a protocol handler description + is equivalent to + {{NavigatorContentUtils/registerProtocolHandler()}}'s |scheme| + argument defined in [[HTML]]. +

    +
    +
    +

    + `url` member +

    +

    + The url member of a protocol handler description is + the URL [=manifest/within scope=] of the application that + opens when the associated protocol is activated. +

    +

    + The url member of a protocol handler description is + equivalent to {{NavigatorContentUtils/registerProtocolHandler()}}'s + url argument defined in [[HTML]]. +

    +
    +
    +

    + Handling a protocol launch +

    +

    + When a protocol handler description + protocol_handler having [=manifest=] manifest + 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. +

    +
    +

    External application resource @@ -2205,6 +2390,12 @@

    could install the web application into a list of bookmarks within the user agent itself.

    +
    +

    + When a web application is installed, a user agent MAY [=register a + protocol handler=]. +

    +

    Application's name @@ -2701,6 +2892,14 @@

    [[MEDIAQUERIES-5]], through which a script can know the display mode of a web application.

    +

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

    @@ -3133,7 +3332,8 @@

    Click to view schema. 
    
+          "https://json.schemastore.org/web-manifest">
+