From 4d272fe1775a7b71d7af251bf2feedd2268ddd55 Mon Sep 17 00:00:00 2001
From: Peter Beverloo <beverloo@beverloo-macbookair.roam.corp.google.com>
Date: Tue, 24 Mar 2015 12:54:49 -0500
Subject: [PATCH] Add a PushSubscriptionOptions dictionary with a userVisible
 option.

User agents may decide to display different UI when requesting push
permission from the user if the intended use of the subscription is to
only send messages which result in user visible UI, for example a
Web Notification.

This PR introduces this in the specification by accepting an optional
property bag to the subscribe() and hasPermission() methods. This bag
features a "userVisible" option that can be set to TRUE.

UAs are not required to follow this UI paradigm, but when they do, they
SHOULD enforce the requirement when receiving a push message. The exact
tools for "user visible UI" and enforcement are left undefined as
one can imagine multiple solutions for them, which we don't want to
capture in the specification.
---
 index.html | 44 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index ee62f66..3a59666 100644
--- a/index.html
+++ b/index.html
@@ -68,6 +68,18 @@
               ]
             },
           ],
+
+          localBiblio: {
+            "NOTIFICATIONS": {
+              title: "Notifications API",
+              href: "https://notifications.spec.whatwg.org/",
+              authors: [
+                "Anne van Kesteren",
+              ],
+              status: "Living Standard",
+              publisher: "WHATWG"
+            }
+          },
       };
     </script>
   </head>
@@ -312,6 +324,10 @@ <h2>
         has been persisted, or a prearranged trust relationship applies. Permissions that are
         preserved beyond the current browsing session MUST be revocable.
       </p>
+      <p>
+        The <a>user agent</a> MAY consider the <code><a>PushSubscriptionOptions</a></code>
+        when acquiring permission or determining the permission status.
+      </p>
       <p>
         When a permission is revoked, all <a title="push subscription">push subscriptions</a>
         created with that permission MUST be <a>deactivated</a>.
@@ -515,13 +531,13 @@ <h2>
       </p>
       <dl title="interface PushManager" class="idl">
         <dt>
-          Promise&lt;PushSubscription&gt; subscribe ()
+          Promise&lt;PushSubscription&gt; subscribe (optional PushSubscriptionOptions options)
         </dt>
         <dt>
           Promise&lt;PushSubscription?&gt; getSubscription ()
         </dt>
         <dt>
-          Promise&lt;PushPermissionStatus&gt; hasPermission ()
+          Promise&lt;PushPermissionStatus&gt; hasPermission (optional PushSubscriptionOptions options)
         </dt>
       </dl>
       <p>
@@ -624,7 +640,7 @@ <h2>
         <li>Return <var>promise</var> and continue the following steps asynchronously.
         </li>
         <li>Retrieve the push permission status (<a><code>PushPermissionStatus</code></a>) of the
-        requesting <a>webapp</a>
+        requesting <a>webapp</a>.
         </li>
         <li>If there is an error, reject <var>promise</var> with no arguments and terminate these
         steps.
@@ -641,6 +657,28 @@ <h2>
         If there is a need to ask for permission, it needs to be done by invoking the
         <a><code>subscribe</code></a> method.
       </p>
+      <section>
+        <h2>
+          <a>PushSubscriptionOptions</a> dictionary
+        </h2>
+        <p>
+          A <a>PushSubscriptionOptions</a> object represents additional options associated with a
+          <a>push subscription</a>. The <a>user agent</a> MAY consider these options when requesting
+          <a>express permission</a> from the user. When an option is considered, the <a>user
+          agent</a> SHOULD enforce it on incoming <a title="push message">push messages</a>.
+        </p>
+        <dl title="dictionary PushSubscriptionOptions" class="idl">
+          <dt>
+            boolean userVisible = false
+          </dt>
+        </dl>
+        <p>
+          The <code><dfn id="widl-PushSubscriptionOptions-userVisible">userVisible</dfn></code>
+          option, when set to <code>true</code>, indicates that the <a>push subscription</a> will
+          only be used for <a title="push message">push messages</a> whose effect is made visible
+          to the user, for example by displaying a Web Notification. [[NOTIFICATIONS]]
+        </p>
+      </section>
     </section>
     <section>
       <h2>