notifications.bs

<pre class=metadata>
Group: WHATWG
H1: Notifications API
Shortname: notifications
Text Macro: TWITTER notifyapi
Text Macro: LATESTRD 2026-01
Abstract: This standard defines an API to display notifications to the end user, typically outside the top-level browsing context's viewport. It is designed to be compatible with existing notification systems, while remaining platform-independent.
Translation: ja https://triple-underscore.github.io/notifications-ja.html
Translation: zh-Hans https://htmlspecs.com/notifications/
Translation: ko https://ko.htmlspecs.com/notifications/
</pre>

<pre class=anchors>
urlPrefix: https://w3c.github.io/vibration/
    urlPrefix: #dfn-; type: dfn
        text: perform vibration
        text: validate and normalize
    urlPrefix: #idl-def-; type: interface
        text: VibratePattern; url: vibratepattern
urlPrefix: https://tc39.github.io/ecma262/
    urlPrefix: #sec-object.; type: dfn
        text: freeze
    url: #sec-list-and-record-specification-type; type: dfn; text: Record
</pre>


<h2 id=terminology>Terminology</h2>

<p>This specification depends on the Infra Standard. [[!INFRA]]

<p>Some terms used in this specification are defined in the DOM, Fetch, High Resolution Time, HTML,
IDL, Service Workers, URL, and Vibration API Standards.
[[!DOM]]
[[!FETCH]]
[[!HR-TIME]]
[[!HTML]]
[[!WEBIDL]]
[[!SERVICE-WORKERS]]
[[!URL]]
[[!VIBRATION]]


<h2 id=notifications>Notifications</h2>

<p>A <dfn id=concept-notification>notification</dfn> is an abstract
representation of something that happened, such as the delivery of a message.

<p>A <a for=/>notification</a> has an associated
<dfn export for=notification id=service-worker-registration>service worker registration</dfn> (null
or a <a for=/>service worker registration</a>). It is initially null.

<p>A <a for=/>notification</a> has an associated <dfn for=notification id=concept-title>title</dfn> (a string).

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=concept-direction>direction</dfn> ("<code>auto</code>", "<code>ltr</code>",
or "<code>rtl</code>").

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=concept-language>language</dfn> (a string).

<p>A <a for=/>notification</a> has an associated <dfn for=notification id=body>body</dfn> (a
string).

<p>A <a for=/>notification</a> has an associated <dfn export for=notification>navigation URL</dfn>
(null or a <a for=/>URL</a>). It is initially null.

<p>A <a for=/>notification</a> has an associated <dfn for=notification id=tag>tag</dfn> (a string).

<p>A <a for=/>notification</a> has an associated <dfn for=notification id=data>data</dfn> (a
<a for=/>Record</a>).

<p>A <a for=/>notification</a> has an associated <dfn for=notification id=timestamp>timestamp</dfn>
(an {{EpochTimeStamp}}).

<p class=note>Timestamps can be used to indicate the time at which a notification
is actual. For example, this could be in the past when a notification is used for
a message that couldn't immediately be delivered because the device was offline,
or in the future for a meeting that is about to start.

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=concept-origin>origin</dfn> (an <a for=/>origin</a>).

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=renotify-preference-flag>renotify preference</dfn> (a boolean). It is
initially false. When true, indicates that the end user should be alerted after the
<a for=/>notification show steps</a> have run with a new notification that has the same
<a for=notification>tag</a> as an existing notification.

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=silent-preference-flag>silent preference</dfn> (null or a boolean). It is
initially null. When true, indicates that no sounds or vibrations should be made. When null,
indicates that producing sounds or vibrations should be left to platform conventions.

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=require-interaction-preference-flag>require interaction preference</dfn>
(a boolean). It is initially false. When true, indicates that on devices with a sufficiently large
screen, the notification should remain readily available until the end user activates or dismisses
the notification.

<p>A <a for=/>notification</a> <em>can</em> have these associated graphics: an
<dfn for=notification id=image-url>image URL</dfn>,
<dfn for=notification id=icon-url>icon URL</dfn>, and
<dfn for=notification id=badge-url>badge URL</dfn>; and their corresponding
<a for=notification>image resource</a>, <a for=notification>icon resource</a>, and
<a for=notification>badge resource</a>.

<p>An <dfn for=notification id=image-resource>image resource</dfn> is a picture shown as part of the
content of the <a for=/>notification</a>, and should be displayed with higher visual priority than the
<a for=notification>icon resource</a> and <a for=notification>badge resource</a>, though it may be
displayed in fewer circumstances.

<p>An <dfn for=notification id=icon-resource>icon resource</dfn> is an image that reinforces the
<a for=/>notification</a> (such as an icon, or a photo of the sender).

<p>A <dfn for=notification id=badge-resource>badge resource</dfn> is an icon representing the web
application, or the category of the <a for=/>notification</a> if the web application sends a wide variety
of <a>notifications</a>. It <em>may</em> be used to represent the <a for=/>notification</a> when there is
not enough space to display the <a for=/>notification</a> itself. It <em>may</em> also be displayed inside
the <a for=/>notification</a>, but then it should have less visual priority than the
<a for=notification>image resource</a> and <a for=notification>icon resource</a>.

<p>A <a for=/>notification</a> has an associated
<dfn for=notification id=vibration-pattern>vibration pattern</dfn> (a <a for=/>list</a>). It is
initially « ».

<p class=note>Developers are encouraged to not convey information through an
<a for=notification lt="image resource">image</a>, <a for=notification lt="icon resource">icon</a>,
<a for=notification lt="badge resource">badge</a>, or <a for=notification>vibration pattern</a> that
is not otherwise accessible to the end user, especially since notification platforms that do not
support these features might ignore them.

<p>A <a for=/>notification</a> has associated <dfn export for=notification id=actions>actions</dfn>
(a <a for=/>list</a> of zero or more <a for=/>notification actions</a>). A
<dfn export id=action>notification action</dfn> represents a choice for an end user. Each
<a for=/>notification action</a> has an associated:

<dl>
 <dt><dfn for="notification action" id=action-name>name</dfn>
 <dd>A string.

 <dt><dfn for="notification action" id=action-title>title</dfn>
 <dd>A string.

 <dt><dfn export for="notification action">navigation URL</dfn>
 <dd>Null or a <a for=/>URL</a>. It is initially null.

 <dt><dfn for="notification action" id=action-icon-url>icon URL</dfn>
 <dd>Null or a <a for=/>URL</a>. It is initially null.

 <dt><dfn for="notification action" id=action-icon-resource>icon resource</dfn>
 <dd>Null or a resource. It is initially null.
</dl>

<p>Users may activate actions, as alternatives to activating the notification itself. The
<dfn>maximum number of actions</dfn> supported is an <a>implementation-defined</a> integer of zero
or more, within the constraints of the notification platform.

<p class=note>Since display of actions is platform-dependent, developers are encouraged to make sure
that any action an end user can invoke from a notification is also available within the web
application.

<p class="note no-backref">Some platforms might modify an
<a for="notification action">icon resource</a> to better match the platform's visual style before
displaying it to the end user, for example by rounding the corners or painting it in a specific
color. Developers are encouraged to use an icon that handles such cases gracefully and does not lose
important information through, e.g., loss of color or clipped corners.

<p>A <dfn>non-persistent notification</dfn> is a <a for=/>notification</a> whose
<a for=notification>service worker registration</a> is null.

<p tracking-vector>A <dfn>persistent notification</dfn> is a <a for=/>notification</a> whose
<a for=notification>service worker registration</a> is non-null.

<hr>

<div algorithm>
<p>To <dfn>create a notification with a settings object</dfn>, given a string <var>title</var>,
{{NotificationOptions}} <a for=/>dictionary</a> <var>options</var>, and
<a for=/>environment settings object</a> <var>settings</var>:

<ol>
 <li><p>Let <var>origin</var> be <var>settings</var>'s
 <a for="environment settings object">origin</a>.

 <li><p>Let <var>baseURL</var> be <var>settings</var>'s
 <a for="environment settings object">API base URL</a>.

 <li><p>Let <var>fallbackTimestamp</var> be the number of milliseconds from the <a>Unix epoch</a> to
 <var>settings</var>'s <a for="environment settings object">current wall time</a>, rounded to the
 nearest integer.

 <li><p>Return the result of <a>creating a notification</a> given <var>title</var>,
 <var>options</var>, <var>origin</var>, <var>baseURL</var>, and <var>fallbackTimestamp</var>.
</ol>
</div>

<div algorithm>
<p>To <dfn export>create a notification</dfn>, given a string <var>title</var>,
{{NotificationOptions}} <a for=/>dictionary</a> <var>options</var>, an <a for=/>origin</a>
<var>origin</var>, a <a for=/>URL</a> <var>baseURL</var>, and an {{EpochTimeStamp}}
<var>fallbackTimestamp</var>:

<ol>
 <li><p>Let <var>notification</var> be a new <a for=/>notification</a>.

 <li><p>If <var>options</var>["{{NotificationOptions/silent}}"] is true and
 <var>options</var>["{{NotificationOptions/vibrate}}"] <a for=map>exists</a>, then <a>throw</a> a
 {{TypeError}}.

 <li><p>If <var>options</var>["{{NotificationOptions/renotify}}"] is true and
 <var>options</var>["{{NotificationOptions/tag}}"] is the empty string, then <a>throw</a> a
 {{TypeError}}.

 <li><p>Set <var>notification</var>'s <a for=notification>data</a> to
 <a abstract-op>StructuredSerializeForStorage</a>(<var>options</var>["{{NotificationOptions/data}}"]).

 <li><p>Set <var>notification</var>'s <a for=notification>title</a> to <var>title</var>.

 <li><p>Set <var>notification</var>'s <a for=notification>direction</a> to
 <var>options</var>["{{NotificationOptions/dir}}"].

 <li><p>Set <var>notification</var>'s <a for=notification>language</a> to
 <var>options</var>["{{NotificationOptions/lang}}"].

 <li><p>Set <var>notification</var>'s <a for=notification>origin</a> to <var>origin</var>.

 <li><p>Set <var>notification</var>'s <a for=notification>body</a> to
 <var>options</var>["{{NotificationOptions/body}}"].

 <li><p>If <var>options</var>["{{NotificationOptions/navigate}}"] <a for=map>exists</a>, then
 <a lt="URL parser">parse</a> it using <var>baseURL</var>, and if that does not return failure, set
 <var>notification</var>'s <a for=notification>navigation URL</a> to the return value. (Otherwise
 <var>notification</var>'s <a for=notification>navigation URL</a> remains null.)

 <li><p>Set <var>notification</var>'s <a for=notification>tag</a> to
 <var>options</var>["{{NotificationOptions/tag}}"].

 <li><p>If <var>options</var>["{{NotificationOptions/image}}"] <a for=map>exists</a>, then
 <a lt="URL parser">parse</a> it using <var>baseURL</var>, and if that does not return failure, set
 <var>notification</var>'s <a>image URL</a> to the return value. (Otherwise
 <var>notification</var>'s <a>image URL</a> is not set.)

 <li><p>If <var>options</var>["{{NotificationOptions/icon}}"] <a for=map>exists</a>, then
 <a lt="URL parser">parse</a> it using <var>baseURL</var>, and if that does not return failure, set
 <var>notification</var>'s <a for=notification>icon URL</a> to the return value. (Otherwise
 <var>notification</var>'s <a for=notification>icon URL</a> is not set.)

 <li><p>If <var>options</var>["{{NotificationOptions/badge}}"] <a for=map>exists</a>, then
 <a lt="URL parser">parse</a> it using <var>baseURL</var>, and if that does not return failure, set
 <var>notification</var>'s <a for=notification>badge URL</a> to the return value. (Otherwise
 <var>notification</var>'s <a for=notification>badge URL</a> is not set.)

 <li><p>If <var>options</var>["{{NotificationOptions/vibrate}}"] <a for=map>exists</a>, then
 <a>validate and normalize</a> it and set <var>notification</var>'s
 <a for=notification>vibration pattern</a> to the return value.

 <li><p>If <var>options</var>["{{NotificationOptions/timestamp}}"] <a for=map>exists</a>, then set
 <var>notification</var>'s <a for=notification>timestamp</a> to the value. Otherwise, set
 <var>notification</var>'s <a for=notification>timestamp</a> to <var>fallbackTimestamp</var>.

 <li><p>Set <var>notification</var>'s <a for=notification>renotify preference</a> to
 <var>options</var>["{{NotificationOptions/renotify}}"].

 <li><p>Set <var>notification</var>'s <a for=notification>silent preference</a> to
 <var>options</var>["{{NotificationOptions/silent}}"].

 <li><p>Set <var>notification</var>'s <a for=notification>require interaction preference</a> to
 <var>options</var>["{{NotificationOptions/requireInteraction}}"].

 <li><p>Set <var>notification</var>'s <a for=notification>actions</a> to « ».

 <li>
  <p>For each <var>entry</var> in <var>options</var>["{{NotificationOptions/actions}}"], up to the
  <a>maximum number of actions</a> supported (skip any excess entries):

  <ol>
   <li><p>Let <var>action</var> be a new <a for=/>notification action</a>.

   <li><p>Set <var>action</var>'s <a for="notification action">name</a> to
   <var>entry</var>["{{NotificationAction/action}}"].

   <li><p>Set <var>action</var>'s <a for="notification action">title</a> to
   <var>entry</var>["{{NotificationAction/title}}"].

   <li><p>If <var>entry</var>["{{NotificationAction/navigate}}"] <a for=map>exists</a>, then
   <a lt="URL parser">parse</a> it using <var>baseURL</var>, and if that does not return failure,
   set <var>action</var>'s <a for="notification action">navigation URL</a> to the return value.
   (Otherwise <var>action</var>'s <a for="notification action">navigation URL</a> remains null.)

   <li><p>If <var>entry</var>["{{NotificationAction/icon}}"] <a for=map>exists</a>, then
   <a lt="URL parser">parse</a> it using <var>baseURL</var>, and if that does not return failure,
   set <var>action</var>'s <a for="notification action">icon URL</a> to the return value. (Otherwise
   <var>action</var>'s <a for="notification action">icon URL</a> remains null.)

   <li><p>Append <var>action</var> to <var>notification</var>'s <a for=notification>actions</a>.
  </ol>

 <li><p>Return <var>notification</var>.
</ol>
</div>


<h3 id=lifetime-and-ui-integrations>Lifetime and UI integration</h3>

<p>The user agent must keep a <dfn>list of notifications</dfn>, which is a <a for=/>list</a> of zero
or more <a>notifications</a>.

<p>User agents should run the <a>close steps</a> for a
<a>non-persistent notification</a> a couple of seconds after they have been
created.

<p>User agents should not display <a>non-persistent notification</a> in a
platform's "notification center" (if available).

<p>User agents should persist <a>persistent notifications</a> until they are
removed from the <a>list of notifications</a>.

<p class=example id=example-38bbd8ee>A <a>persistent notification</a> could have the
{{Notification/close()}} method invoked of one of its {{Notification}} objects.

<p>User agents should display <a>persistent notifications</a> in a platform's
"notification center" (if available).


<h3 id="permissions-integration">Permissions integration</h3>

<p>The Notifications API is a <a>powerful feature</a> which is identified by the
<a for="powerful feature">name</a> "<dfn export permission><code>notifications</code></dfn>".
[[!Permissions]]

<div algorithm>
<p>To <dfn>get the notifications permission state</dfn>, run these steps:

<ol>
 <li><p>Let <var>permissionState</var> be the result of <a>getting the current permission state</a>
 with "<a permission><code>notifications</code></a>".

 <li><p>If <var>permissionState</var> is "<code>prompt</code>", then return "<code>default</code>".

 <li><p>Return <var>permissionState</var>.
</ol>
</div>


<h3 id=direction>Direction</h3>

<p>This section is written in terms equivalent to those used in the Rendering
section of HTML. [[!HTML]]

<!-- keep this in sync with
     https://html.spec.whatwg.org/multipage/rendering.html#text-rendered-in-native-user-interfaces -->

<p>User agents are expected to honor the Unicode semantics of the text of a
<a for=/>notification</a>'s <a for=notification>title</a>, <a for=notification>body</a>, and the
<a for="notification action">title</a> of each of its <a for=notification>actions</a>. Each is
expected to be treated as an independent set of one or more bidirectional algorithm
paragraphs when displayed, as defined by the bidirectional algorithm's rules P1,
P2, and P3, including, for instance, supporting the paragraph-breaking behavior
of U+000A LINE FEED (LF) characters. For each paragraph of the
<a for=notification>title</a>, <a for=notification>body</a> and the
<a for="notification action">title</a> of each of the <a for=notification>actions</a>, the
<a for=/>notification</a>'s
<a for=notification>direction</a> provides the higher-level override of
rules P2 and P3 if it has a value other than "<code>auto</code>". [[!BIDI]]

<p>The <a for=/>notification</a>'s <a for=notification>direction</a> also determines the relative
order in which the <a for=/>notification</a>'s <a for=notification>actions</a> should be displayed
to the end user, if the notification platform displays them side by side.


<h3 id=language>Language</h3>

<!-- keep this in sync with
     https://html.spec.whatwg.org/multipage/dom.html#attr-lang -->

<p>The <a for=/>notification</a>'s <a for=notification>language</a> specifies the primary language
for the <a for=/>notification</a>'s <a for=notification>title</a>, <a for=notification>body</a> and
the <a for=notification>title</a> of each of its <a for=notification>actions</a>. Its value is a
string. The empty string indicates that the primary language is unknown. Any other string must be
interpreted as a language tag. Validity or well-formedness are not enforced. [[!BCP47]]

<p class=note>Developers are encouraged to only use valid language tags.


<h3 id=resources>Resources</h3>

<div algorithm>
<p>The <dfn>fetch steps</dfn> for a given <a for=/>notification</a> <var>notification</var> are:

<ol>
 <!-- XXX image fetching is underspecified: https://github.com/whatwg/html/issues/4474 -->
 <li>
  <p>If the notification platform supports images, <a for=/>fetch</a>
  <var>notification</var>'s <a>image URL</a>, if <a>image URL</a> is set.

  <p class=note>The intent is to fetch this resource similar to an
  <a href="https://html.spec.whatwg.org/multipage/images.html#update-the-image-data"><code>&lt;img&gt;</code></a>,
  but this <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=24055">needs abstracting</a>.

  <p>Then, <a>in parallel</a>:

  <ol>
   <li><p>Wait for the <a for=/>response</a>.

   <li><p>If the <a for=/>response</a>'s <a>internal response</a>'s <a for=response>type</a> is
   "<code>default</code>", then attempt to decode the resource as image.

   <li><p>If the image format is supported, set <var>notification</var>'s
   <a for=notification>image resource</a> to the decoded resource. (Otherwise
   <var>notification</var> has no <a for=notification>image resource</a>.)
  </ol>

 <li>
  <p>If the notification platform supports icons, <a for=/>fetch</a>
  <var>notification</var>'s <a for=notification>icon URL</a>, if <a for=notification>icon URL</a>
  is set.

  <p class=note>The intent is to fetch this resource similar to an
  <a href="https://html.spec.whatwg.org/multipage/images.html#update-the-image-data"><code>&lt;img&gt;</code></a>,
  but this <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=24055">needs abstracting</a>.

  <p>Then, <a>in parallel</a>:

  <ol>
   <li><p>Wait for the <a for=/>response</a>.

   <li><p>If the <a for=/>response</a>'s <a>internal response</a>'s <a for=response>type</a> is
   "<code>default</code>", then attempt to decode the resource as image.

   <li><p>If the image format is supported, set <var>notification</var>'s
   <a for=notification>icon resource</a> to the decoded resource. (Otherwise
   <var>notification</var> has no <a for=notification>icon resource</a>.)
  </ol>

 <li>
  <p>If the notification platform supports badges, <a for=/>fetch</a> <var>notification</var>'s
  <a for=notification>badge URL</a>, if <a for=notification>badge URL</a> is set.

  <p class=note>The intent is to fetch this resource similar to an
  <a href="https://html.spec.whatwg.org/multipage/images.html#update-the-image-data"><code>&lt;img&gt;</code></a>,
  but this <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=24055">needs abstracting</a>.

  <p>Then, <a>in parallel</a>:

  <ol>
   <li><p>Wait for the <a for=/>response</a>.

   <li><p>If the <a for=/>response</a>'s <a>internal response</a>'s <a for=response>type</a> is
   "<code>default</code>", then attempt to decode the resource as image.

   <li><p>If the image format is supported, set <var>notification</var>'s
   <a for=notification>badge resource</a> to the decoded resource. (Otherwise
   <var>notification</var> has no <a for=notification>badge resource</a>.)
  </ol>

 <li>
  <p>If the notification platform supports actions and action icons, then for each <var>action</var>
  in <var>notification</var>'s <a for=notification>actions</a>: if
  <a for="notification action">icon URL</a> is non-null, <a for=/>fetch</a> <var>action</var>'s
  <a for="notification action">icon URL</a>.

  <p class=note>The intent is to fetch this resource similar to an
  <a href="https://html.spec.whatwg.org/multipage/images.html#update-the-image-data"><code>&lt;img&gt;</code></a>,
  but this <a href="https://github.com/whatwg/html/issues/4474">needs abstracting</a>.

  <p>Then, <a>in parallel</a>:

  <ol>
   <li><p>Wait for the <a for=/>response</a>.

   <li><p>If the <a for=/>response</a>'s <a>internal response</a>'s <a for=response>type</a> is
   "<code>default</code>", then attempt to decode the resource as image.

   <li><p>If the image format is supported, then set <var>action</var>'s
   <a for="notification action">icon resource</a> to the decoded resource. (Otherwise
   <var>action</var>'s <a for="notification action">icon resource</a> remains null.)
  </ol>
</ol>
</div>


<h3 id=showing-a-notification>Showing a notification</h3>

<div algorithm>
<p>The <dfn export>notification show steps</dfn> for a given <a for=/>notification</a>
<var>notification</var> are:
<!-- These steps are invoked from "in parallel" steps -->

<ol>
 <li><p>Run the <a>fetch steps</a> for <var>notification</var>.

 <li><p>Wait for any <a for=/ lt=fetch>fetches</a> to complete and <var>notification</var>'s
 <a for=notification>image resource</a>, <a for=notification>icon resource</a>, and
 <a for=notification>badge resource</a> to be set (if any), as well as the
 <a for="notification action">icon resources</a> for the <var>notification</var>'s
 <a for=notification>actions</a> (if any).

 <li><p>Let <var>shown</var> be false.

 <li><p>Let <var>oldNotification</var> be the <a for=/>notification</a> in the
 <a>list of notifications</a> whose <a for=notification>tag</a> is not the empty string and is
 <var>notification</var>'s <a for=notification>tag</a>, and whose <a for=notification>origin</a> is
 <a>same origin</a> with <var>notification</var>'s <a for=notification>origin</a>, if any, and null
 otherwise.

 <li>
  <p>If <var>oldNotification</var> is non-null:

  <ol>
   <li><p><a>Handle close events</a> with <var>oldNotification</var>.

   <li>
    <p>If the notification platform supports replacement:

    <ol>
     <li><p><a for=list>Replace</a> <var>oldNotification</var> with <var>notification</var>, in the
     <a>list of notifications</a>.

     <li><p>Set <var>shown</var> to true.
    </ol>

    <p class="note no-backref">Notification platforms are strongly encouraged to support native
    replacement as it leads to a better user experience.

   <li><p>Otherwise, <a for=list>remove</a> <var>oldNotification</var> from the
   <a>list of notifications</a>.
  </ol>

 <li>
  <p>If <var>shown</var> is false:

  <ol>
   <li><p><a for=list>Append</a> <var>notification</var> to the <a>list of notifications</a>.

   <li><p>Display <var>notification</var> on the device (e.g., by calling the appropriate
   notification platform API).
  </ol>

 <li><p>If <var>shown</var> is false or <var>oldNotification</var> is non-null, and
 <var>notification</var>'s <a for=notification>renotify preference</a> is true, then run the
 <a>alert steps</a> for <var>notification</var>.

 <li><p>If <var>notification</var> is a <a>non-persistent notification</a>, then <a>queue a task</a>
 to <a>fire an event</a> named <code>show</code> on the {{Notification}} object representing
 <var>notification</var>.
</ol>
</div>


<h3 id=activating-a-notification>Activating a notification</h3>

<div algorithm="activate steps">
<p>When a <a for=/>notification</a> <var>notification</var>, or one of its
<a for=notification>actions</a>, is activated by the end user, assuming the underlying notification
platform supports activation, the user agent must (unless otherwise specified) run these steps:

<ol>
 <li><p>Let <var>action</var> be null.

 <li><p>If one of <var>notification</var>'s <a for=notification>actions</a> was activated by the end
 user, then set <var>action</var> to that <a for=/>notification action</a>.

 <li><p>Let <var>navigationURL</var> be <var>notification</var>'s
 <a for=notification>navigation URL</a>.

 <li>
  <p>If <var>action</var> is non-null, then set <var>navigationURL</var> to <var>action</var>'s
  <a for="notification action">navigation URL</a>.

  <p class=note>This intentionally makes it so that when a <a for=/>notification action</a>'s
  <a for="notification action">navigation URL</a> is null, it falls through to the
  <code>click</code> event, providing more flexibility to the web developer.

 <li>
  <p>If <var>navigationURL</var> is non-null:

  <ol>
   <li>
    <p>Select one of the following two options in an <a>implementation-defined</a> manner:

    <ul>
     <li><p><a for=/>Navigate</a> an existing <a for=/>top-level traversable</a> within the user
     agent's <a for="user agent">top-level traversable set</a> to <var>navigationURL</var>.
     <!-- Should maybe set userInvolvement to "browser UI" here and below. -->

     <li><p><a>Create a fresh top-level traversable</a> given <var>navigationURL</var>.
    </ul>

    <p class=note>User agents are strongly encouraged to match platform conventions.

   <li><p>Return.
  </ol>

 <li>
  <p>If <var>notification</var> is a <a>persistent notification</a>:

  <ol>
   <li><p>Let <var>actionName</var> be the empty string.

   <li><p>If <var>action</var> is non-null, then set <var>actionName</var> to <var>action</var>'s
   <a for="notification action">name</a>.

   <li><a>Fire a service worker notification event</a> named "<code>notificationclick</code>" given
   <var>notification</var> and <var>actionName</var>.
  </ol>

 <li>
  <p>Otherwise, <a>queue a task</a> to run these steps:

  <ol>
   <li>
    <p>Let <var>intoFocus</var> be the result of <a lt="fire an event">firing an event</a> named
    <code>click</code> on the {{Notification}} object representing <var>notification</var>, with its
    {{Event/cancelable}} attribute initialized to true.

    <p class="note">User agents are encouraged to make {{Window/focus()}} work from within the event
    listener for the event named <code>click</code>.

   <li><p>If <var>intoFocus</var> is true, then the user agent should bring the
   <var>notification</var>'s related <a for=/>browsing context</a>'s viewport into focus.
  </ol>
</ol>

<p class="note">Throughout the web platform "activate" is intentionally misnamed as "click".
</div>


<h3 id=closing-a-notification>Closing a notification</h3>

<p>When a <a for=/>notification</a> is closed, either by the underlying notification platform or by
the end user, the <a>close steps</a> for it must be run.

<div algorithm>
<p>The <dfn>close steps</dfn> for a given <a for=/>notification</a> <var>notification</var> are:

<ol>
 <li><p>If the <a>list of notifications</a> does not <a for=list>contain</a>
 <var>notification</var>, then abort these steps.

 <li><p><a>Handle close events</a> with <var>notification</var>.

 <li><p><a for=list>Remove</a> <var>notification</var> from the <a>list of notifications</a>.
</ol>
</div>

<div algorithm>
<p>To <dfn>handle close events</dfn> given a <a for=/>notification</a> <var>notification</var>:

<ol>
 <li><p>If <var>notification</var> is a <a>persistent notification</a> and <var>notification</var>
 was closed by the end user, then <a>fire a service worker notification event</a> named
 "<code>notificationclose</code>" given <var>notification</var>.

 <li><p>If <var>notification</var> is a <a>non-persistent notification</a>, then <a>queue a task</a>
 to <a>fire an event</a> named <code>close</code> on the {{Notification}} object representing
 <var>notification</var>.
</ol>
</div>


<h3 id=alerting-the-user>Alerting the end user</h3>

<div algorithm>
<p>The <dfn>alert steps</dfn> for alerting the end user about a given <a for=/>notification</a>
<var>notification</var> are:

<ol>
 <li><p><a>Perform vibration</a> using <var>notification</var>'s
 <a for=notification>vibration pattern</a>, if any.
</ol>
</div>


<h2 id=api>API</h2>

<pre class=idl>
[Exposed=(Window,Worker)]
interface Notification : EventTarget {
  constructor(DOMString title, optional NotificationOptions options = {});

  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static Promise&lt;NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);

  static readonly attribute unsigned long maxActions;

  attribute EventHandler onclick;
  attribute EventHandler onshow;
  attribute EventHandler onerror;
  attribute EventHandler onclose;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute USVString navigate;
  readonly attribute DOMString tag;
  readonly attribute USVString image;
  readonly attribute USVString icon;
  readonly attribute USVString badge;
  [SameObject] readonly attribute FrozenArray&lt;unsigned long> vibrate;
  readonly attribute EpochTimeStamp timestamp;
  readonly attribute boolean renotify;
  readonly attribute boolean? silent;
  readonly attribute boolean requireInteraction;
  [SameObject] readonly attribute any data;
  [SameObject] readonly attribute FrozenArray&lt;NotificationAction> actions;

  undefined close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  USVString navigate;
  DOMString tag = "";
  USVString image;
  USVString icon;
  USVString badge;
  VibratePattern vibrate;
  EpochTimeStamp timestamp;
  boolean renotify = false;
  boolean? silent = null;
  boolean requireInteraction = false;
  any data = null;
  sequence&lt;NotificationAction> actions = [];
};

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};

dictionary NotificationAction {
  required DOMString action;
  required DOMString title;
  USVString navigate;
  USVString icon;
};

callback NotificationPermissionCallback = undefined (NotificationPermission permission);
</pre>

<p>A <a>non-persistent notification</a> is represented by one {{Notification}}
object and can be created through {{Notification}}'s
<a constructor lt="Notification(title, options)">constructor</a>.

<p>A <a>persistent notification</a> is represented by zero or more
{{Notification}} objects and can be created through the
{{ServiceWorkerRegistration/showNotification()}} method.


<h3 id=garbage-collection>Garbage collection</h3>

<p>A {{Notification}} object must not be garbage collected while the <a>list of notifications</a>
<a for=list>contains</a> its corresponding <a for=/>notification</a> and it has an
<a for=/>event listener</a> whose <b>type</b> is <code>click</code>, <code>show</code>,
<code>close</code>, or <code>error</code>.


<h3 id=constructors>Constructors</h3>

<div algorithm>
<p>The
<dfn constructor for=Notification lt="Notification(title, options)"><code>new Notification(<var>title</var>, <var>options</var>)</code></dfn>
constructor steps are:

<ol>
 <li><p>If <a>this</a>'s <a>relevant global object</a> is a {{ServiceWorkerGlobalScope}} object,
 then <a>throw</a> a {{TypeError}}.

 <li>
  <p>If <var>options</var>["{{NotificationOptions/actions}}"] is not <a for=list>empty</a>, then
  <a>throw</a> a {{TypeError}}.

  <p class=note><a>Actions</a> are only supported for <a>persistent notifications</a>.

 <li><p>Let <var>notification</var> be the result of
 <a>creating a notification with a settings object</a> given <var>title</var>, <var>options</var>,
 and <a>this</a>'s <a>relevant settings object</a>.

 <li><p>Associate <a>this</a> with <var>notification</var>.

 <li>
  <p>Run these steps <a>in parallel</a>:

  <ol>
   <li><p>If <a>this</a>'s <a>relevant settings object</a>'s
   <a for="environment settings object">origin</a> is not <a>same origin</a> with <a>this</a>'s
   <a>relevant settings object</a>'s <a for="environment">top-level origin</a> or the result of
   <a>getting the notifications permission state</a> is not "<code>granted</code>", then
   <a>queue a task</a> to <a>fire an event</a> named <code>error</code> on <a>this</a>, and abort
   these steps.

   <li><p>Run the <a for=/>notification show steps</a> for <var>notification</var>.
  </ol>
</ol>
</div>


<h3 id=static-members>Static members</h3>

<div algorithm>
<p>The static <dfn attribute for=Notification><code>permission</code></dfn> getter steps are to
return the result of <a>getting the notifications permission state</a>.
</div>

<div class=note>
 <p>If you edit standards please refrain from copying the above. Synchronous permissions are like
 synchronous IO, a bad idea.

 <p>Developers are encouraged to use the Permissions {{Permissions/query()}} method
 instead. [[Permissions]]

 <pre class="example" id="permissions-query-example">
    const permission = await navigator.permissions.query({name: "notifications"});
    if (permission.state === "granted") {
       // We have permission to use the API…
    }
 </pre>
</div>

<div algorithm>
<p>The static
<dfn method for=Notification><code>requestPermission(<var>deprecatedCallback</var>)</code></dfn>
method steps are:

<ol>
 <li><p>Let <var>global</var> be the <a>current global object</a>.

 <li><p>Let <var>promise</var> be <a for=/>a new promise</a> in <a>this</a>'s <a>relevant Realm</a>.

 <li>
  <p>Run these steps <a>in parallel</a>:

  <ol>
   <li><p>Let <var>permissionState</var> be "<code>denied</code>".

   <li><p>If <a>this</a>'s <a>relevant settings object</a>'s
   <a for="environment settings object">origin</a> is <a>same origin</a> with <a>this</a>'s
   <a>relevant settings object</a>'s <a for="environment">top-level origin</a>, then set
   <var>permissionState</var> to the result of <a>requesting permission to use</a>
   "<a permission><code>notifications</code></a>".

   <li>
    <p><a>Queue a global task</a> on the <a>DOM manipulation task source</a> given <var>global</var>
    to run these steps:

    <ol>
     <li><p>If <var>deprecatedCallback</var> is given, then <a for=/>invoke</a>
     <var>deprecatedCallback</var> with « <var>permissionState</var> » and "<code>report</code>".

     <li><p><a for=/>Resolve</a> <var>promise</var> with <var>permissionState</var>.
    </ol>
  </ol>

 <li><p>Return <var>promise</var>.
</ol>
</div>

<p class="warning">Notifications are the one instance thus far where asking the end user upfront
makes sense. Specifications for other APIs should not use this pattern and instead employ one of the
<a href="http://robert.ocallahan.org/2011/06/permissions-for-web-applications_30.html">many more suitable alternatives</a>.

<p>The static <dfn attribute for=Notification><code>maxActions</code></dfn> getter steps are to
return the <a>maximum number of actions</a> supported.

<h3 id=object-members>Object members</h3>

<p>The following are the <a>event handlers</a> (and their corresponding
<a>event handler event types</a>) that must be supported as attributes by the
{{Notification}} object.

<table>
  <thead>
    <tr>
      <th><a>event handler</a>
      <th><a>event handler event type</a>
 <tbody>
  <tr>
   <td><dfn attribute for=Notification><code>onclick</code></dfn>
   <td><code>click</code>
  <tr>
   <td><dfn attribute for=Notification><code>onshow</code></dfn>
   <td><code>show</code>
  <tr>
   <td><dfn attribute for=Notification><code>onerror</code></dfn>
   <td><code>error</code>
  <tr>
   <td><dfn attribute for=Notification><code>onclose</code></dfn>
   <td><code>close</code>
</table>

<p>The <dfn method for=Notification><code>close()</code></dfn> method steps are to run the
<a>close steps</a> for <a>this</a>'s <a for=/>notification</a>.

<p>The <dfn attribute for=Notification><code>title</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>title</a>.

<p>The <dfn attribute for=Notification><code>dir</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>direction</a>.

<p>The <dfn attribute for=Notification><code>lang</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>language</a>.

<p>The <dfn attribute for=Notification><code>body</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>body</a>.

<p>The <dfn attribute for=Notification><code>navigate</code></dfn> getter steps are:

<ol>
 <li><p>If <a>this</a>'s <a>notification</a>'s <a for=notification>navigation URL</a> is null, then
 return the empty string.

 <li><p>Return <a>this</a>'s <a>notification</a>'s <a for=notification>navigation URL</a>,
 <a lt="URL serializer">serialized</a>.
</ol>

<p>The <dfn attribute for=Notification><code>tag</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>tag</a>.

<p>The <dfn attribute dfn-for=Notification><code>image</code></dfn> getter steps are:

<ol>
 <li><p>If there is no <a>this</a>'s <a for=/>notification</a>'s <a for=notification>image URL</a>, then
 return the empty string.

 <li><p>Return <a>this</a>'s <a for=/>notification</a>'s <a for=notification>image URL</a>,
 <a lt="URL serializer">serialized</a>.
</ol>

<p>The <dfn attribute for=Notification><code>icon</code></dfn> getter steps are:

<ol>
 <li><p>If there is no <a>this</a>'s <a for=/>notification</a>'s <a for=notification>icon URL</a>, then
 return the empty string.

 <li><p>Return <a>this</a>'s <a for=/>notification</a>'s <a for=notification>icon URL</a>,
 <a lt="URL serializer">serialized</a>.
</ol>

<p>The <dfn attribute for=Notification><code>badge</code></dfn> getter steps are:

<ol>
 <li><p>If there is no <a>this</a>'s <a for=/>notification</a>'s <a for=notification>badge URL</a>, then
 return the empty string.

 <li><p>Return <a>this</a>'s <a for=/>notification</a>'s <a for=notification>badge URL</a>,
 <a lt="URL serializer">serialized</a>.
</ol>

<p>The <dfn attribute for=Notification><code>vibrate</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>vibration pattern</a>.

<p>The <dfn attribute for=Notification><code>timestamp</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>timestamp</a>.

<p>The <dfn attribute for=Notification><code>renotify</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>renotify preference</a>.

<p>The <dfn attribute for=Notification><code>silent</code></dfn> getter steps are to return
<a>this</a>'s <a for=/>notification</a>'s <a for=notification>silent preference</a>.

<p>The <dfn attribute for=Notification><code>requireInteraction</code></dfn> getter steps are to
return <a>this</a>'s <a for=/>notification</a>'s <a for=notification>require interaction preference</a>.

<p>The <dfn attribute for=Notification><code>data</code></dfn> getter steps are to return
<a abstract-op>StructuredDeserialize</a>(<a>this</a>'s <a for=/>notification</a>'s
<a for=notification>data</a>, <a>this</a>'s <a>relevant Realm</a>). If this throws an exception,
then return null.
<!-- Relies on SameObject becoming Cached as proposed -->

<p>The <dfn attribute for=Notification><code>actions</code></dfn> getter steps are:

<ol>
 <li><p>Let <var>frozenActions</var> be an empty list of type {{NotificationAction}}.

 <li>
  <p><a for=list>For each</a> <var>entry</var> of <a>this</a>'s <a for=/>notification</a>'s
  <a for=notification>actions</a>:

  <ol>
   <li><p>Let <var>action</var> be a new {{NotificationAction}}.

   <li><p>Set <var>action</var>["{{NotificationAction/action}}"] to <var>entry</var>'s
   <a for="notification action">name</a>.

   <li><p>Set <var>action</var>["{{NotificationAction/title}}"] to <var>entry</var>'s
   <a for="notification action">title</a>.

   <li><p>If <var>entry</var>'s <a for="notification action">navigation URL</a> is non-null, then
   set <var>action</var>["{{NotificationAction/navigate}}"] to <var>entry</var>'s
   <a for="notification action">navigation URL</a>, <a lt="URL serializer">serialized</a>.

   <li><p>If <var>entry</var>'s <a for="notification action">icon URL</a> is non-null, then set
   <var>action</var>["{{NotificationAction/icon}}"] to <var>entry</var>'s
   <a for="notification action">icon URL</a>, <a lt="URL serializer">serialized</a>.

   <!-- XXX IDL dictionaries are usually returned by value, so don't need to be
        immutable. But FrozenArray reifies the dictionaries to mutable JS
        objects accessed by reference, so we explicitly freeze them.
        It would be better to do this with IDL primitives instead of JS - see
        https://www.w3.org/Bugs/Public/show_bug.cgi?id=29004 -->
   <li><p>Call <a lt="freeze">Object.freeze</a> on <var>action</var>, to
   prevent accidental mutation by scripts.

   <li><p>Append <var>action</var> to <var>frozenActions</var>.
  </ol>

 <li><p>Return the result of <a>create a frozen array</a> from <var>frozenActions</var>.
</ol>

<h3 id=examples>Examples</h3>

<h4 id=using-events>Using events from a page</h4>

<p><a lt="non-persistent notification">Non-persistent</a> {{Notification}}
objects dispatch events during their lifecycle, which developers can use to
generate desired behaviors.

<p>The <code>click</code> event dispatches when the end user activates a notification.

<pre class=example id=example-08e8ecea>
var not = new Notification("Gebrünn Gebrünn by Paul Kalkbrenner", { icon: "newsong.svg", tag: "song" });
not.onclick = function() { displaySong(this); };</pre>


<h4 id=using-actions>Using actions from a service worker</h4>

<p><a lt="persistent notification">Persistent notifications</a> fire
<code>notificationclick</code> events on the {{ServiceWorkerGlobalScope}}.

<p>Here a service worker shows a notification with a single "Archive"
<a for=/>notification action</a>, allowing end users to perform this common task from the
notification without having to open the website (for example, the notification platform might show a
button on the notification). The end user can also activate the main body of the notification to
open their inbox.

<pre class=example id=example-50e7c86c>
self.registration.showNotification("New mail from Alice", {
  actions: [{action: 'archive', title: "Archive"}]
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  if (event.action === 'archive') {
    silentlyArchiveEmail();
  } else {
    clients.openWindow("/inbox");
  }
}, false);</pre>


<h4 id=tags-example>Using the <code>tag</code> member for multiple instances</h4>

<p>Web applications frequently operate concurrently in multiple instances, such as when an end user
opens a mail application in multiple browser tabs. Since the desktop is a shared resource, the
notifications API provides a way for these instances to easily coordinate, by using the
<code>tag</code> member.

<p>Notifications which represent the same conceptual event can be tagged in the same way, and when
both are shown, the end user will only receive one notification.

<pre class=example id=example-2e2c735a>
Instance 1                                   | Instance 2
                                             |
// Instance notices there is new mail.       |
new Notification("New mail from John Doe",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // Slightly later, this instance notices
                                             |  // there is new mail.
                                             |  new Notification("New mail from John Doe",
                                             |                   { tag: 'message1' });</pre>

<p>The result of this situation, if the user agent follows the algorithms here, is a
<strong>single</strong> notification "New mail from John Doe".


<h4 id=using-the-tag-member-for-a-single-instance>Using the <code>tag</code> member for a single instance</h4>

<p>The <code>tag</code> member can also be used by a single instance of an
application to keep its notifications as current as possible as state changes.

<p>For example, if Alice is using a chat application with Bob, and Bob sends
multiple messages while Alice is idle, the application may prefer that Alice not
see a desktop notification for each message.

<pre class=example id=example-a1d95db4>
// Bob says "Hi"
new Notification("Bob: Hi", { tag: 'chat_Bob' });

// Bob says "Are you free this afternoon?"
new Notification("Bob: Hi / Are you free this afternoon?", { tag: 'chat_Bob' });</pre>

<p>The result of this situation is a <i>single</i> notification; the second one
replaces the first having the same tag. In a platform that queues notifications
(first-in-first-out), using the tag allows the notification to also maintain its
position in the queue. Platforms where the newest notifications are shown first,
a similar result could be achieved using the {{Notification/close()}} method.


<h2 id=service-worker-api>Service worker API</h2>

<pre class=idl>
dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise&lt;undefined> showNotification(DOMString title, optional NotificationOptions options = {});
  Promise&lt;sequence&lt;Notification>> getNotifications(optional GetNotificationOptions filter = {});
};

[Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  constructor(DOMString type, NotificationEventInit eventInitDict);

  readonly attribute Notification notification;
  readonly attribute DOMString action;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
  DOMString action = "";
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
  attribute EventHandler onnotificationclose;
};
</pre>

<p>A <a for=/>service worker registration</a> has an associated
<dfn export for="service worker registration">has <code>showNotification()</code> been successfully invoked</dfn>
(a <a for=/>boolean</a>), which is initially false.

<p class=note>This is infrastructure for the <cite>Push API</cite> standard. [[PUSH-API]]

<div algorithm>
<p>The
<dfn method for=ServiceWorkerRegistration><code>showNotification(<var>title</var>, <var>options</var>)</code></dfn>
method steps are:

<ol>
 <li><p>Let <var>global</var> be <a>this</a>'s <a>relevant global object</a>.

 <li><p>Let <var>promise</var> be <a>a new promise</a> in <a>this</a>'s <a>relevant Realm</a>.

 <li><p>If <a>this</a>'s <a for="service worker registration">active worker</a> is null, then
 <a for=/>reject</a> <var>promise</var> with a {{TypeError}} and return <var>promise</var>.
 <!-- We might have to throw directly here and below, see
      https://github.com/web-platform-tests/wpt/pull/24601 -->

 <li><p>Let <var>notification</var> be the result of
 <a>creating a notification with a settings object</a> given <var>title</var>, <var>options</var>,
 and <a>this</a>'s <a>relevant settings object</a>. If this threw an exception, then
 <a for=/>reject</a> <var>promise</var> with that exception and return <var>promise</var>.

 <li><p>Set <var>notification</var>'s <a for=notification>service worker registration</a> to
 <a>this</a>.

 <li>
  <p>Run these steps <a>in parallel</a>:

  <ol>
   <li><p>If the result of <a>getting the notifications permission state</a> is not
   "<code>granted</code>", then <a>queue a global task</a> on the
   <a>DOM manipulation task source</a> given <var>global</var> to <a for=/>reject</a>
   <var>promise</var> with a {{TypeError}}, and abort these steps.

   <li><p>Run the <a for=/>notification show steps</a> for <var>notification</var>.

   <li><p>Set <var>notification</var>'s <a for=notification>service worker registration</a>'s
   <a for="service worker registration">has <code>showNotification()</code> been successfully invoked</a>
   to true.

   <li><p><a>Queue a global task</a> on the <a>DOM manipulation task source</a> given
   <var>global</var> to <a for=/>resolve</a> <var>promise</var> with undefined.
  </ol>

 <li><p>Return <var>promise</var>.
</ol>
</div>

<div algorithm>
<p>The
<dfn method for=ServiceWorkerRegistration><code>getNotifications(<var>filter</var>)</code></dfn>
method steps are:

<ol>
 <li><p>Let <var>global</var> be <a>this</a>'s <a>relevant global object</a>.

 <li><p>Let <var>realm</var> be <a>this</a>'s <a>relevant Realm</a>.

 <li><p>Let <var>origin</var> be <a>this</a>'s <a>relevant settings object</a>'s
 <a for="environment settings object">origin</a>.
 <!-- Arguably this should snapshot origin somehow so that changes to it do not impact the
      in parallel part. -->

 <li><p>Let <var>promise</var> be <a for=/>a new promise</a> in <var>realm</var>.

 <li>
  <p>Run these steps <a>in parallel</a>:

  <ol>
   <li><p>Let <var>tag</var> be <var>filter</var>["{{GetNotificationOptions/tag}}"].

   <li><p>Let <var>notifications</var> be a <a for=/>list</a> of all <a>notifications</a> in the
   <a>list of notifications</a> whose <a for=notification>origin</a> is <a>same origin</a> with
   <var>origin</var>, whose <a for=notification>service worker registration</a> is <a>this</a>, and
   whose <a for=notification>tag</a>, if <var>tag</var> is not the empty string, is <var>tag</var>.

   <li>
    <p><a>Queue a global task</a> on the <a>DOM manipulation task source</a> given <var>global</var>
    to run these steps:

    <ol>
     <li><p>Let <var>objects</var> be a <a for=/>list</a>.

     <li><p><a for=list>For each</a> <a for=/>notification</a> in <var>notifications</var>, in creation
     order, create a <a for=/>new</a> {{Notification}} object with <var>realm</var> representing
     <a for=/>notification</a>, and <a for=list>append</a> it to <var>objects</var>.

     <li><p><a for=/>Resolve</a> <var>promise</var> with <var>objects</var>.
    </ol>
  </ol>

 <li><p>Return <var>promise</var>.
</ol>

<p class=note>This method returns zero or more new {{Notification}} objects which might represent
the same underlying <a for=/>notification</a> of {{Notification}} objects already in existence.
</div>

<hr>

<div algorithm>
<p>To <dfn>fire a service worker notification event</dfn> named <var>name</var> given a
<a for=/>notification</a> <var>notification</var>, and an optional string <var>action</var> (default
the empty string): run <a>Fire Functional Event</a> given <var>name</var>, {{NotificationEvent}},
<var>notification</var>'s <a for=notification>service worker registration</a>, and the following
initialization:

<dl>
 <dt>{{NotificationEvent/notification}}
 <dd>A new {{Notification}} object representing <var>notification</var>.
 <dt>{{NotificationEvent/action}}
 <dd><var>action</var>
</dl>
</div>

<div algorithm>
<p>The <dfn attribute for=NotificationEvent><code>notification</code></dfn> getter steps are to
return the value it was initialized to.
</div>

<div algorithm>
<p>The <dfn attribute for=NotificationEvent><code>action</code></dfn> getter steps are to return the
value it was initialized to.
</div>

<p>The following is the <a>event handler</a> (and its corresponding
<a>event handler event type</a>) that must be supported as attribute by the
{{ServiceWorkerGlobalScope}} object:

<table>
  <thead>
    <tr>
      <th><a>event handler</a>
      <th><a>event handler event type</a>
  <tbody>
    <tr>
      <td><dfn attribute for=ServiceWorkerGlobalScope><code>onnotificationclick</code></dfn>
      <td><code>notificationclick</code>
    <tr>
      <td><dfn attribute for=ServiceWorkerGlobalScope><code>onnotificationclose</code></dfn>
      <td><code>notificationclose</code>
</table>


<h2 id=acknowledgments class=no-num>Acknowledgments</h2>

<p>Thanks to
Addison Phillips,
Aharon (Vladimir) Lanin,
Alex Russell,
Anssi Kostiainen,
Arkadiusz Michalski,
Boris Zbarsky,
Brady Eidson,
David Håsäther,
Doug Turner,
Drew Wilson,
Ehsan Akhgari,
Frederick Hirsch,
Ian Hickson,
Jake Archibald,
James Graham,
John Mellor,
Jon Lee,
Jonas Sicking,
Kagami Sascha Rosylight<!-- saschanaz; GitHub -->,
Michael Cooper,
Michael Henretty,
Michael™ Smith,
Michael van Ouwerkerk,
Mike Taylor,
Nicolás Satragno,
Olli Pettay,
Peter Beverloo,
Philip Jägenstedt,
Reuben Morais,
Rich Tibbett,
Robert Bindar,
박상현 (Sanghyun Park),
Simon Pieters,
Theresa O'Connor,
timeless, and
triple-underscore
for being awesome.

<p>This standard is written by <a lang=nl href=https://annevankesteren.nl/>Anne van Kesteren</a>
(<a href=https://www.apple.com/>Apple</a>, <a href=mailto:annevk@annevk.nl>annevk@annevk.nl</a>). An
earlier iteration was written by John Gregg (<a href=https://www.google.com/>Google</a>,
<a href=mailto:johnnyg@google.com>johnnyg@google.com</a>).