Re: [w3c/push-api] Rewrite introduction to clarify applicability and use cases (#218)

beverloo commented on this pull request.

This looks great, thanks!

> @@ -151,47 +151,47 @@
         Introduction
       </h2>
       <p>
+        The Push API allows a <a>webapp</a> to communicate with a <a>user agent</a> asynchronously.
+        This allows a <a>webapp</a> to provide the <a>user agent</a> with time-sensitive
+        information whenever that information becomes known, rather than waiting for a user to open
+        the <a>webapp</a>.

We define _webapp_ as the code executed by the UA, where _application server_ is the server-side component of a _webapp_.

As such, it's the _application server_ that is enabled to communicate with the _webapp_, and thereby the _user agent_, asynchronously. It seems to me like the first two occurrences of _webapp_ have to be _application server_, and the occurrences of _user agent_ should be _webapp_?

>          As defined here, <a>push services</a> support delivery of <a>application server</a>
-        messages in the following contexts and related use cases:
+        messages at any time.

> ... support delivery of \<a>push messages\</a> at any time.

> +        message</a> might be used to inform the user of an incoming WebRTC call.
+      </p>
+      <p>
+        A <a>push message</a> can also be sent when the <a>user agent</a> is temporarily offline.
+        In support of this, the <a>push service</a> stores messages for the <a>user agent</a> until
+        the <a>user agent</a> becomes available. This supports use cases where a <a>webapp</a>
+        learns of changes that occur while a user is offline and ensures that the <a>user agent</a>
+        can be provided with relevant information in a timely fashion. For example, a user that is
+        away from network access might receive a new message; the message is stored by the <a>push
+        service</a> until the <a>user agent</a> becomes reachable and the message can be delivered.
+      </p>
+      <p>
+        The Push API will also ensure reliable delivery of push messages while a <a>user agent</a>
+        is actively using a <a>webapp</a>, for instance if a user is actively using the
+        <a>webapp</a> or the <a>webapp</a> has an active worker, frame, or background window.
+        However, as mentioned, these are not the primary use case for the API.

nit: s/use case/use cases/

Is it worth emphasizing that while they're not the primary use cases, it's still something developers should consider when the frequency of messages is low enough? We shouldn't advocate the WebRTC call application to maintain a connection of their own when all it does is waiting for incoming calls.

> +        away from network access might receive a new message; the message is stored by the <a>push
+        service</a> until the <a>user agent</a> becomes reachable and the message can be delivered.
+      </p>
+      <p>
+        The Push API will also ensure reliable delivery of push messages while a <a>user agent</a>
+        is actively using a <a>webapp</a>, for instance if a user is actively using the
+        <a>webapp</a> or the <a>webapp</a> has an active worker, frame, or background window.
+        However, as mentioned, these are not the primary use case for the API.
+      </p>
+      <p>
+        Push messaging is best suited to occasions where there is not already an active
+        communications channel established between <a>user agent</a> and <a>webapp</a>. Sending a
+        <a>push message</a> requires considerably more resources when compared with more direct
+        methods of communication such as <a href="https://fetch.spec.whatwg.org/">fetch()</a> or
+        <a href="https://html.spec.whatwg.org/multipage/comms.html#network">websockets</a>. <a>Push
+        message</a> usually have higher latency than direct communications and they can also be

nit: s/Push message/Push messages/

> +      </p>
+      <p>
+        In particular, a <a>push message</a> will be delivered to the <a>webapp</a> even if that
+        <a>webapp</a> is not currently active in a browser window: this relates to use cases in
+        which the user may close the <a>webapp</a>, but still benefits from the <a>webapp</a> being
+        able to be restarted when a <a>push message</a> is received. For example, a <a>push
+        message</a> might be used to inform the user of an incoming WebRTC call.
+      </p>
+      <p>
+        A <a>push message</a> can also be sent when the <a>user agent</a> is temporarily offline.
+        In support of this, the <a>push service</a> stores messages for the <a>user agent</a> until
+        the <a>user agent</a> becomes available. This supports use cases where a <a>webapp</a>
+        learns of changes that occur while a user is offline and ensures that the <a>user agent</a>
+        can be provided with relevant information in a timely fashion. For example, a user that is
+        away from network access might receive a new message; the message is stored by the <a>push
+        service</a> until the <a>user agent</a> becomes reachable and the message can be delivered.

"For example, a user that...can be delivered." just repeats the previous sentence. I think we can drop it.

> +        service</a> until the <a>user agent</a> becomes reachable and the message can be delivered.
+      </p>
+      <p>
+        The Push API will also ensure reliable delivery of push messages while a <a>user agent</a>
+        is actively using a <a>webapp</a>, for instance if a user is actively using the
+        <a>webapp</a> or the <a>webapp</a> has an active worker, frame, or background window.
+        However, as mentioned, these are not the primary use case for the API.
+      </p>
+      <p>
+        Push messaging is best suited to occasions where there is not already an active
+        communications channel established between <a>user agent</a> and <a>webapp</a>. Sending a
+        <a>push message</a> requires considerably more resources when compared with more direct
+        methods of communication such as <a href="https://fetch.spec.whatwg.org/">fetch()</a> or
+        <a href="https://html.spec.whatwg.org/multipage/comms.html#network">websockets</a>. <a>Push
+        message</a> usually have higher latency than direct communications and they can also be
+        subject to restrictions on use. Most push services limit the size and quantity of <a>push

nit: s/push services/\<a>push services\</a>/

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/push-api/pull/218#pullrequestreview-7212573