On some platforms the button rendered for a NotificationAction can display an icon. This example shows it on an Android phone and watch.

I propose adding a simple icon attribute (like the one on NotificationOptions):

USVString icon;

See http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Aug/0017.html

To allow for transient notifications.

Also make the "notification center" concept more explicit, while allowing for implementation to have various strategies around it.

Consider trying to write a Promise-based wrapper for showing a non-persistent* notification:

https://notifications.spec.whatwg.org/#constructors defines two kinds of errors: TypeErrors can be thrown synchronously, and are easy to catch, but a permission error can also be thrown asynchronously. However there is no corresponding asynchronous onshow callback to tell that the notification was successfully shown.

So it seems the only way to know if you've successfully shown an error, is using setTimeout/postTask to queue a task, and hope that it executes after the permission check. e.g.:

function showNotification(title, options) {
    return new Promise(function(resolve, reject) {
        try {
            var notification = new Notification(title, options);
        } catch (ex) {
            reject(ex);
            return;
        }
        var errored = false;
        notification.onerror = function() {
            errored = true;
            reject.apply(arguments);
        }
        setTimeout(function() {
            if (!errored)
                resolve();
        }, 0); // TODO: Is 0 enough?
    });
}

This seems really fragile.

*: Of course, this becomes moot if #26 deprecates non-persistent notifications.

This issue relates to issue #46.

To the degree that it makes sense to state document-conformance requirements for values provided in scripts (as opposed to provided in HTML markup), we should consider making BCP-47-validity for lang values a document-conformance requiring (aka authoring requirement) rather than a requirement that we place on UAs.

Is there a reason step 5.1 has to be in parallel?
"
If permission for notification’s origin is not "granted", reject promise with a TypeError exception, and terminate these substeps.
"
Gecko will be doing the permission check in serial. I don't think that violates anything in the spec, but just wanted to confirm.

Step 2 of the constructor algorithm notes:
"If entry settings object's global object is a ServiceWorkerGlobalScope object, throw a TypeError exception."

Creating a NotificationEvent uses the NotificationEventInit dictionary, which has a required attribute of type Notification.

How would one actually give this attribute a value?

+@johnmellor

See http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Aug/0017.html

@sicking, I guess this should just mimic the timestamp used for Date objects? Do we expect applications to worry about timezones?

I've got two thoughts on Notification.data.

1. Let's limit it to persistent notifications. Since there are no onshow/onclose events anymore it doesn't add any value to non-persistent ones.
2. Do we want to impose a maximum size for the data payload? I'm hearing the theoretical concern of people storing loads (>megabytes) of data in there.

I'm not a fan of arbitrary limits, but it does make sense to do so in order to prevent abuse. I expect our implementation to impose a limit of sorts, but am not sure yet where to draw the line.

Abstract

It would be useful to have progress based notifications, that allow you to indicate the current progress of a long running task.

Justification

Aside from the usefulness of telling a user that a task is in progress, Android devices in particular already have this feature natively:

Proposal

I propose having a read only property on the notification called "progress". It expects a floating point value between 0 and 1.

Creating a new notification with the same tag as a previous notification, but a different progress float gives the UA an opportunity to display a progress bar for this notification. Other UAs will not be effected, and will gracefully continue doing what they do.

Example

# Contrived progress example, but could be done with Streams based on current/total.
var progress = 0.1;
setTimeout(function updateProgress() {
    progress += 0.1;
    if (progress < 1) {
        new Notification('Downloading...', {
            body: 'Downloading file.zip',
            progress: 0.1,
            tag:'download/file.zip'
        });
        setTimeout(updateProgress, 500);
    }
}, 500);

According to the WEBIDL spec [1] we should have an interface type for the custom data object when used with the [SameObject] attribute [2].

[1] http://heycam.github.io/webidl/#SameObject
[2] notifications.spec.whatwg.org/#api

See http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Aug/0065.html for suggestions.

I apologize if this has already been discussed before, but it would be extremely useful to have a timestamp property, or perhaps createTime, on the notification object. A scenario I am thinking is when a page wants to manually expire notifications that have been around for a certain amount of time (without the user making any action to dismiss them). Cross-global notifications make this difficult.

The Notification() constructor and ServiceWorkerRegistration.showNotification() seem to have the same parameters. Would it make sense to expose Notification() to service workers?

See https://bugs.chromium.org/p/chromium/issues/detail?id=590029 for some more discussion.

Need to see if http://html5.org/r/8660 applies somehow.

Some mobile platforms show notifications on their lock-screen (prior to the user logging in), which is great for a quick peek about what's going on, but not so great for notifications that contain rather sensitive content. In these cases, an implementation could decide to display a more generic/anonymized version instead.

How about adding a sensitive (boolean) option, defaulting to false?

@jakearchibald

"
Let notification be the result of creating a notification given title and options. If this threw an exception, reject promise with that exception and return promise.

If context object’s active worker is null, reject promise with a TypeError exception and return promise.
"
Better to not create a notification at all if there is no active worker.

Need to use list of availabe images, sniffing, SVG support, etc. See https://www.w3.org/Bugs/Public/show_bug.cgi?id=24055

Notification.data is yet another storage mechanism on the platform which is a bit sad to see. We could easily imagine that Notifications have an id that could be used to store data associated to them instead.

The only issue with that would be that the Notifications could be closed in which casee the applications might have stored data worth cleaning up but could forget about it. Given that they can read the currently open notifications, it is definitely something applications can handle but we can imagine some will do it wrong. Though, if they do it wrong, they only harm themselves by increasing their disk usage.

Having arbitrary data on Notifications can be scary because it adds new form of storage that isn't clearly related to the page lifecycle which might lead to scary bugs (data leaking).
It will also increase the general complexity of the platform with regards to data. Things like quota will have to take into account Notification.data to prevent this to be abused.
It will also increase implementation complexity significantly: storing an ID on the notification is probably supported by most platforms, raw and arbitrary data isn't AFAIK.

An alternative to killing Notification.data would be to restrict the size of what can be stored in them. We want that to be interoperable so that size limitation should be specfied.

From @sicking:

I think we should have a defined way for an author to bring forward a
page when the notification is clicked.

This could be either a property on the notification
"openCreatingWindowWhenNotificationIsClickedPlease: true".

Or define that a service worker is notified about a click, and then
enable the service worker to find a particular window (which may or
may not be connected to the service worker) and be able to bring that
window to the foreground.

Or a way for a window to be notified when the notification is clicked
such that it can bring itself forward using window.focus().

Or something else.

The goal is to be able to answer the question "If I'm a web developer
and want to bring forward the window connected to a notification when
the notification is clicked, what code should I write?"

Could maybe hook this into service workers in some way as they will get the ability to spawn windows and maybe focus them.

@beverloo proposed something: http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Jul/0204.html

See my feedback: http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Aug/0011.html

Need to get feedback from Apple, Microsoft, and Mozilla ideally.

The NotificationOptions dictionary contains four keys which aren't being reflected on Notification objects: renotify, silent, noscreen and sticky.

What's the reason for not adding them? While I don't foresee any major use-cases, it allows for feature detection and manual cloning of notifications. Implementation cost is near zero for us.

Happy to write a PR.

Android 4.1+, Chrome Apps and Mozilla XUL all allow authors to specify a priority for each notification.

This has various possible use cases:

• It influences notification ordering;
• On Android, high priority notifications are initially shown as a heads-up notification that overlaps the screen, before retreating to the notification shade;
• On desktop, it can be used as a hint to determine how long the notification should remain on screen - this is based on frequent partner feedback that desktop users get annoyed by notifications cluttering their screens until manually dismissed.

A complication here is that different platforms are likely to use different scales for priority. The most effective way to mitigate that seems to be to provide detailed (but non-normative) examples of what kinds of notifications are covered by each priority level, as in Android's Correctly set and manage notification priority documentation, in order to have a shared frame of reference.

As a strawman, I'd suggest that we standardize that same 5-point scale, with the same descriptions.

@sicking @beverloo

As a means of focusing the active window when a user clicks the notification. Context: https://bugzilla.mozilla.org/show_bug.cgi?id=874050

I collect a few minor things to improve, here they are:

4.9 Displaying notifications
http://notifications.spec.whatwg.org/#displaying-notifications

1. If displaying fails (e.g. the notification platform returns an error), for each Notification object representing notification, queue
   a task to fire an event named error on notification and terminate
   these steps. << "named error on notification..." probably should be
   "named error on Notification object..."

like we have in:

1. For each Notification object representing notification, queue a
   task to fire an event named show on the Notification object.

4.9 Displaying notifications
http://notifications.spec.whatwg.org/#displaying-notifications

In this algo (step 1.) we have more detailed the process of
downloading icons. But in algo 4.10 Replacing a notification (step 1
.) probably remained the old style (what we still have in W3C spec for
this cases). So better use in 4.10 for icon the same style like in
4.9. In the other site I'm not sure what description is more correct (use one style in both algos is indicated).

And in 4.9 (step 1.) after "image" and before " Once" should be dot (".").

getClones(filter)
http://notifications.spec.whatwg.org/#dom-notification-getclones

1. For each notification in notification, in creation order, create a
   new Notification object representing notification and push that object
   to objects. << not "For each notification in notifications..."?

5.2 Constructors
http://notifications.spec.whatwg.org/#constructors

1. Set notifications's origin to the current origin. << second origin
   refer to the same place as first origin, W3C refer to
   http://tools.ietf.org/html/rfc6454#section-4, but you can be more
   precise.

4.5 Showing a notification
http://notifications.spec.whatwg.org/#showing-a-notification

1. If the device allows notifications to be displayed immediately
   without limitations on the number of concurrent notifications, run the
   display steps and terminate these steps. << "...run the display steps
   for notification..."

Android 4.1+, iOS 8+, Chrome Apps and Mozilla XUL all support showing action buttons at the bottom of a notification. This allows users to quickly handle the most common tasks for a particular notification, without having to open the originating application.

We'd like to add action buttons to the Notifications API, and implement them in Chrome.

Strawman API:

dictionary NotificationAction {
    DOMString id;  // If clicked, this will become NotificationEvent.actionId
    DOMString title;  // Button text
}
partial dictionary NotificationOptions {
    sequence<NotificationAction> actions;
}
partial interface Notification {
    FrozenArray<NotificationAction> actions;
}
partial interface NotificationEvent {
    DOMString actionId;  // Id of clicked action, or null if user clicked notification body instead
}

Action support would be feature detected via Notification.prototype.hasOwnProperty('actions'). UAs which expose that must support up to 2 actions. If more than 2 actions are provided in NotificationOptions.actions, throw a TypeError. The number 2 was chosen because it's the maximum supported by iOS and Chrome OS, and although Android supports 3 buttons, Chrome for Android already uses one of the available slots to show a link to per-origin settings. (If later UAs want to support more actions, we could add a maxSupportedActions constant to Notification).

Presentation of actions would be implementation-defined, for example on Android action buttons are only shown when the notification is expanded. Hence websites should not rely on actions, and should provide the same functionality via alternate UI that can be reached by clicking on the notification body.

I explicitly left out action icons, since only Android supports them, and Android currently only supports icon resources shipped in a native app's apk (not icons downloaded at runtime), so they wouldn't be implementable yet there either.

@sicking @beverloo

Chrome currently keeps all notifications on the screen indefinitely (for desktop).

Most notifications can be moved to an off-screen notification center automatically. We've received feedback that some major players use setTimeout() in a Service Worker to automatically remove a notification from the user's screen after a number of seconds. This is a huge hack and only works because of Chrome's Service Worker-lifetime heuristics :/.

However, some notifications can't. Consider a calendar which may choose for a notification to remain on-screen until the event has finished. Other notifications that require the user to act may also prefer a more persistent display.

We'd like to start auto-closing them, as the vast majority of users and developers prefer this, but would like an option for developers to opt-in to keeping them on the screen if they deem this important.

What about an autominimize property, a boolean defaulting to true? The name certainly needs some bikeshedding. I'd prefer not to have the minimize-time specified by developers to avoid breaking user expectations.

+@sicking

The specification currently defines the "vibrate" option in the NotificationOptions dictionary, but doesn't expose the attribute because of the following bug:
https://www.w3.org/Bugs/Public/show_bug.cgi?id=23682

Because of this, developers cannot feature detect whether vibration is available, and won't be able to clone or serialize notifications that use vibration either. This is inconsistent with all other attributes of the Notification object.

For fixing this issue, I think that we should continue the discussion in Bug 23682, and update the Notification API when an appropriate solution has been found there.

Blink is ready to ship support for vibrate options. and we support the vibrate attribute for testing purposes, but do not plan to ship it at this time

Blink implementation is as following:
[WebIDL]
readonly attribute sequence<unsigned long>? vibrate;

To give a few examples:

1. new Notification('Title', {}).vibrate returns "null"
2. new Notification('Title', { vibrate: 10 }).vibrate returns "[10]"
3. new Notification('Title', { vibrate: [10, 0] }).vibrate returns "[10]"
   • In this case, vibrate pattern is sanitized.
4. new Notification('Title', { vibrate: [10, 20, 30] }).vibrate returns "[10, 20, 30]"

All returned arrays will be new objects.

Thanks
Sanghyun Park

See http://discourse.specifiction.org/t/native-numerical-notifications/566 for the rough idea.

Consider the following example:

var n = new Notification({...});
n = null;
// later...
Notification.get({...});

The results of get() change depending on whether n has been GC'd between clobbering the reference and calling get().

ES6 defines TypeError in section 19.5.5.5 as: "Indicates the actual type of an operand is different than the expected type."

The Notification specification throws TypeErrors when:

1. silent is set to true, but either sound or vibrate has been defined.
2. renotify is set to true, but tag is an empty string.
3. sticky is defined for non-persistent notifications.
4. A non-persistent notification is being constructed on the ServiceWorkerGlobalScope.
5. There is no active worker on the given ServiceWorkerRegistration.
6. No permission has been granted when showing persistent notifications.

(1) and (2) are similar to how Object.observe() is specified to behave. IDB uses a ConstraintError which by name sounds more appropriate to me (after all, the the type being passed it's accurate, but its value is unexpected), but are there concerns for overloading this for database constraints v.s. input value constraints?

(3) might be more appropriate as a NotSupportedError. Given that non-persistent notifications are specified to auto-close, it wouldn't make sense (even if the passed type is correct.)

I'm on the fence between NotSupportedError and InvalidStateError for (4), but am erring towards the former. type would refer to the type of the global, and that's by no means clear.

(5) sounds like an InvalidStateError to me, referring to the Service Worker not being in the active state.

I'm not sure about (6). Is it common to use SecurityError in these cases?

As a developer I think it's strange that calling new Notification without appropriate permission succeeds and returns a notification object as if it was displayed.

I would expect it to throw an error or somehow indicate the call failed.

Seems it might not be appropriate for Safari. http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Apr/0075.html

Credit: Josh Aas

Gecko is experimenting with a six second timeout.

At some point there was a close event proposed for Notifications (https://developer.mozilla.org/en-US/docs/Web/API/Notification/onclose) which no longer seems to be in the spec.

It would be useful to have this event for stats and ultimately shaping when developers send notifications (you can imagine a scenario of realizing that send push messages on specific categories are always closed by the user so the site reduces the number of pushes for that category).

Is there a reason this isn't supported by the spec?

I don't have opinions at the moment, but:

1. Are Notifications created on the main thread retrievable in Notification.get() on a worker and vice-versa? There are various synchronization issues for both implementers and users, because persistence adds shared memory.
2. Notification.get() requires re-use of Notification objects when available, what happens when worker and main thread refer to the same notification (not in JS, but in the underlying storage, via tag or id or whatever)
3. Behaviour when one of the threads decides to call close()

These are what I can think of now.

NotificationEventInit is a dictionary with a required notification member. As such, script cannot avoid passing the NotificationEventInit dictionary to the NotificationEvent constructor, so it should not be marked as optional.

https://notifications.spec.whatwg.org/#service-worker-api

Any context which has access to a ServiceWorkerRegistration object can display persistent notifications, which includes Documents. However, only Service Workers can access the list of existing notifications.

What about having ServiceWorkerRegistration.getNotifications(...) instead?

It seems using a structured clone makes the most sense. Transfering objects won't work here. It's not entirely clear to me what the best is for Blob, File, etc. Effectively the page can shut down, but they will still be kept alive through this Notification. I guess it's not too different from what Indexed DB can do.

Is what what we want?

My proposal would be to add a data member to NotificationsOptions and a data property to Notification objects. The constructor does a structured clone so that the data property returns a fresh object and its established the object can indeed be cloned. I guess we'd also have to keep a copy alive somewhere in case we need to create a new instance of the Notification object (e.g. when Notification.get() is used).

Need to make sure we properly understand where and when the cloning happens in case that becomes an observable hook some day. (Or make sure we revisit it then.)

https://notifications.spec.whatwg.org/#notifications

If options’s lang is either a valid BCP 47 language tag or the empty string, set notification’s language to options’s lang, and set it to the empty string otherwise. [LANG]

No UAs that implement Web Notifications currently do any checking at all of the value of the lang option given to the Notification constructor—neither for validity nor for the basic microsyntax/datatype of the value. Instead they all just pass the value on as-is such that it becomes the value of the lang property of the Notification instance. The only case where the lang value given to the constructor will result in the empty string as the value of the lang property of an instance is if the empty string for the lang option is given to the constructor.

So it seems we’re unlikely to get UAs to implement the existing requirement, and I think at this point we should consider changing this step to simply say:

Set notification's language to options's lang.

What is correct behaviour for algo 4.6 Activating a notification? Only
firing click event or may be other actions? I ask because in Firefox
when we activate notification then browser automatic close this
notification and firing close event. In Chrome we have only click
event for this action.

https://bugzilla.mozilla.org/show_bug.cgi?id=875114#c32

And about note:

"User agents are strongly encouraged to make window.focus() work from within the event listener for the event named click as a means of focusing the browsing context related to the notification."

So this means that UA can automatically trigger window.focus() or we must use this method in event listener every time when we want move focus to related browsing context? Currently, it seems that only Firefox acts as first described (automatically trigger focus()).

Following on from w3c/ServiceWorker#602 (comment), notificationclick handlers should be able to focus/open windows via the clients API in the ServiceWorker.

A typical pattern would be:

self.addEventListener('notificationclick', function(event) {
  if (event.notification.tag == 'chat') {
    client.matchAll().then(clients => {
      return clients.find(c => new URL(c.url).pathname.indexOf('/chat/') === 0);
    }).then(client => {
      if (client) {
        client.focus();
      }
      else {
        clients.openWindow('/chat/');
      }
    });
  }
});

Since .matchAll is async, does the spec need to take this into account to allow focusing/opening of windows?

https://html.spec.whatwg.org/#allowed-to-show-a-popup mentions a user-agent defined timeframe of ~4 seconds.

The specification currently defines two types of notifications, persistent and non-persistent ones, identified by whether they're associated with a Service Worker or not.

If we were to design the Notification API today, would we still have this distinction? I don't think we would.

Reliability of the notifications obviously is the primary motivation behind this, and I don't think I have to repeat any of the other arguments that backed introduction of persistent notifications in the first place.

A number of pieces of functionality of non-persistent notifications have been removed recently, notably the show and close events. What about going taking another jump, and deprecating support for them altogether?

For Chrome for Android, we're ready to ship Service Workers-based notifications, and would very much prefer to not ship non-persistent notifications if we can find a path towards deprecating them.

It sounds like the spec meant to say:

1. Otherwise, create a new Notification object representing notification and push that object to /objects/.

Just a minor thought:

It feels strange to me that in Chrome, dismissing the permission infobar for Notifications resolves the promise with 'denied', but Notification.permission is set to 'default'.

I can still write the code I want, and maybe this is the best option, but the semantics definitely feel strange since I didn't 'deny' the request, I simply 'deferred' it.

I don't know what the solution is here, but I wonder if 'deferring' or 'ignoring' a permission request is a common enough pattern that UAs may wish to implement that it should be first class in the API.

Ho hum.

The replace steps should be more clear regarding whether the notifying actions (e.g. playing a sound, vibrate the device) should be triggered again.

Currently Notifications support a single image to be defined, but on today's world of many different screen densities we may want to consider a syntax for multiple syntax.

My proposal is to adopt the Web Manifest's syntax for defining an icon size:
http://w3c.github.io/manifest/#icons-member

This would look as follows:

registration.showNotification('My Notification', {
  body: 'Hello, world!',
  icon: '/legacy-icon.png',  // optional, only used as fall-back
  icons: [
    { src: '/icon-1x.png',
      type: 'image/png',
      density: 1 },
    { src: '/icon-2x.png',
      density: 2 },
    { src: 'icon.ico',
      sizes: '128x128 256x256' }
  ]
});

On a tangent, we may also want to consider some sort of "small icon", to be used when the platform displays such icons in a status bar. (E.g. my little flag man on Android -- we're going to show a generic Notification icon when shipping them.)

+@mounirlamouri

(editorial)

https://notifications.spec.whatwg.org/#dom-serviceworkerregistration-shownotification

(1) Let promise be a new promise.
(2) Let notification be the result of creating a notification given title and options. Rethrow any exceptions.
(3) If context object's active worker is null, reject promise with a TypeError exception.

I see that WebIDL defines some additional steps for promises - if a function returning a Promise value throws an exception, rather than throwing the exception it'll reject the promise.

Can we change the showNotification() algorithm to point this out explicitly? I found this rather confusing, and it took me quite a while to figure out where that behavior comes from.

Loosely following the fetch spec's formulation, what about the following amendment to the showNotification() steps?

1. Let notification be the result of creating a notification given title and options. If that threw an exception, reject promise with that exception.

Developers can specify renotify to indicate whether sounds and vibrations should be applied when a notification has been replaced.

We can clarify the effects of this in a number of ways:

• The replace steps (2.10) should:
  • describe that the UA does not have to fetch the sound resource when renotify === false.
  • describe that the sound should be played, and the vibration pattern performed, when renotify === true.
• The note in the same section (2.10) should say that the side effects may apply depending on the renotify flag.

We can address this by introducing "alert steps", which encapsulate playing the sound and performing the vibration. Hypothetical alert mechanisms such as light indicators could be included there too.

If a persistent notification with the require Interaction flag not set is left and is automatically removed from the display, should the notificationclose event fire? I think it should.

Right now in Chrome it does not, and looking at the spec and #52 it is not clear if it should or not (the language I think is a little vague).

The spec says wrt to require interaction flag:

When set, indicates that on devices with a sufficiently large screen, the notification should remain readily available until the user activates or dismisses the notification.

The spec also says close steps should only apply to persistent notifications when the user or system dismisses the notification, and a persistent notification is a notification with an attached service worker.

Checking Chrome's implementation, when in a service worker there is a notification on the screen self.registration.getNotifications().then(function(e) {console.log(e);}) will list the notification objects, when the timeout for the display occurs self.registration.getNotifications().then(function(e) {console.log(e);}) will then have an empty list. This implies the item has been removed from the notification list and should have the event fired. But chrome I think is spec compliant in this case.

In my head at least, there needs to be clarity around the definition of the requireInteractionFlag should say 'the notification should remain in the list of notifications until the user activates or dismisses the notification', without this it is not saying clearly that the close steps should be run or not when the system times out notification.