From 4c24e73b3013316b9f39d196bca2eb8867027e6a Mon Sep 17 00:00:00 2001 From: Aaron Gustafson Date: Mon, 4 Nov 2019 10:06:17 -0800 Subject: [PATCH] Add shortcuts feature to the explainer and spec (#768) Adding shortcuts to the explainer --- explainer.md | 56 +++++++++++++++ index.html | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 249 insertions(+) diff --git a/explainer.md b/explainer.md index da0e1c5a0..106b4c838 100644 --- a/explainer.md +++ b/explainer.md @@ -194,6 +194,62 @@ TBW: using description and screenshots. ## Theme color and background color TBW... +## Adding shortcuts +Numerous operating systems grant native applications the ability to add menu items to the app icon itself. These often provide quick access to key tasks for an app. Typically, these are exposed via a right click, long tap, or a similar context menu-triggering action. For web applications, you can define a set of shortcuts to be exposed when the app is installed. Each shortcut item must have a name and a target URL. You may also include additional information, such as a shorter name, a description for the action, and one or more icons. + +```JSON +"shortcuts": [ + { + "name": "Play Later", + "description": "View the list of podcasts you saved for later", + "url": "/play-later", + "icons": [ + { + "src": "/icons/play-later.svg", + "type": "image/svg+xml", + "purpose": "any" + } + ] + }, + { + "name": "Subscriptions", + "description": "View the list of podcasts you listen to", + "url": "/subscriptions", + "icons": [ + { + "src": "/icons/subscriptions.svg", + "type": "image/svg+xml", + "purpose": "any" + } + ] + }, + { + "name": "Search", + "description": "Search for new podcasts to listen to", + "url": "/search", + "icons": [ + { + "src": "/icons/search.svg", + "type": "image/svg+xml", + "purpose": "any" + } + ] + }, + { + "name": "Discover", + "description": "Browse for new podcasts to listen to", + "url": "/discover", + "icons": [ + { + "src": "/icons/discover.svg", + "type": "image/svg+xml", + "purpose": "any" + } + ] + } +] +``` + ## 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 9e240d4b6..c0929ef36 100644 --- a/index.html +++ b/index.html @@ -1558,6 +1558,10 @@

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

    ServiceWorkerRegistrationObject serviceworker; sequence<ExternalApplicationResource> related_applications; boolean prefer_related_applications = "false"; + sequence<ShortcutItem> shortcuts; };

    @@ -2403,6 +2408,102 @@

    can get their games and apps rated with IARC.

    +
    +

    + shortcuts member +

    +

    + The shortcuts member is an array of + ShortcutItems that provide access to key tasks within a web + application. +

    +

    + Shortcuts could, for instance, be used to link directly to a user's + timeline within a social media application or to their recent orders + in an e-commerce context. +

    +

    + How shortcuts are presented, and how many of them are shown to the + user, is at the discretion of the user agent and/or operating system. +

    +

    + Developers are encouraged to order their shortcuts by priority, with + the most critical shortcuts appearing first in the array. +

    +

    + The steps for processing the shortcuts member + are given by the following algorithm. The algorithm takes a + sequence<ShortcutItem> + shortcuts as an argument. This algorithm returns an + sequence<ShortcutItem>. For + each shortcut (ShortcutItem) in the sequence, set + shortcut.icons to the result of running processing + `ImageResource` members given shortcut.icons and + manifest URL. For each shortcut + (ShortcutItem) in the sequence, parse + shortcut["url"] using manifest URL as + the base URL. +

    +

    + A user agent SHOULD expose shortcuts via interactions that are + consistent with exposure of an application icon's context menu in the + host operating system (e.g., right click, long press). A user agent + SHOULD render the shortcuts in the same order as they are provided in + the manifest. A user agent SHOULD represent the shortcuts in a manner + consistent with exposure of an application icon's context menu in the + host operating system. A user agent MAY truncate the list of + shortcuts 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 shortcuts. + Assuming the the manifest's URL is + https://example.com/manifest.webmanifest: +

    +
      +
    • The first shortcut would be displayed with the text "Play + Later". If the operating system supports icons for context menu + items and it also supports SVG images for that purpose, the user + agent would present + https://example.com/icons/play-later.svg next to the + text. When launched, the user agent would instantiate a new + top-level browsing context and navigate to + https://example.com/play-later. +
      • +
    • The first shortcut would be displayed with the text + "Subscriptions". When launched, the user agent would instantiate a + new top-level browsing context and navigate to + https://example.com/subscriptions?sort=desc. +
      • +
    + 
    +            {
+              "shortcuts": [
+                {
+                  "name": "Play Later",
+                  "description": "View the list of podcasts you saved for later",
+                  "url": "/play-later",
+                  "icons": [
+                    {
+                      "src": "/icons/play-later.svg",
+                      "type": "image/svg+xml",
+                      "purpose": "any"
+                    }
+                  ]
+                },
+                {
+                  "name": "Subscriptions",
+                  "description": "View the list of podcasts you listen to",
+                  "url": "/subscriptions?sort=desc"
+                }
+              ]
+            }
+
    +
    +

    @@ -2953,6 +3054,98 @@

    +
    +

    + ShortcutItem and its members +

    + 
    +        dictionary ShortcutItem {
+          required USVString name;
+          USVString short_name;
+          USVString description;
+          required USVString url;
+          sequence<ImageResource> icons;
+        };
+
    +

    + Each ShortcutItem represents a link to a key task or page within + a web app. A user agent can use these values to assemble a context menu + to be displayed by the operating system when a user engages with the + web app's icon. When the user invokes a shortcut from the operating + system menu, the user agent SHOULD run Launching a shortcut. +

    +
    +

    + name member +

    +

    + The name member of a ShortcutItem is a + string that represents the name of the shortcut as it is + usually displayed to the user in a context menu. +

    +
    +
    +

    + short_name member +

    +

    + The short_name member of a ShortcutItem is a + string that represents a short version of the name of the + shortcut. It is intended to be used where there is insufficient space + to display the full name of the shortcut. +

    +
    +
    +

    + description member +

    +

    + The description member of a ShortcutItem is a + string that allows the developer to describe the purpose of + the shortcut. User agents MAY expose this information to assistive + technology. +

    +
    +
    +

    + url member +

    +

    + The url member of a ShortcutItem is the URL + that opens when the associated shortcut is activated. +

    +
    +
    +

    + icons member +

    +

    + The icons member of an ShortcutItem member is an + array of ImageResources that can serve as iconic + representations of the shortcut in various contexts. +

    +
    +
    +

    + Launching a shortcut +

    +

    + When ShortcutItem shortcut having + WebAppManifest manifest is invoked, run the + following steps: +

    +
      +
    1. Let url be shortcut.url. +
      2. +
    2. Let browsing context be the result of creating a new + top-level browsing context. +
      3. +
    3. + Navigate browsing context to url. +
      4. +
    +
    +

    Multi-purpose members