Push notifications are a way for websites to send small messages to users when the user is not on the site. iOS and Android devices already support their own push notification services, but we want to make notifications available to the whole web.

Client API

The API will be an object at navigator.push with this interface:

interface PushManager {
  DOMRequest requestURL();
  DOMRequest getCurrentURL();
  DOMRequest revokeURL();
}

requestURL() asks the user if they'd like to allow this site to send notifications. When the success callback runs, request.result will be a "JSON object" with the following structure

dictionary PushURLResult {
  DOMString url;
  DOMString[] supportedVersions;
  boolean userMessages;
  boolean appMessages;
  boolean appBadges;
}

The url property contains the URL which the site can send messages to this user. It's up to the site to send the URL to the backend for storage.

The supportedVersions property contains a list of server-protocol versions that the server supports. The website should always use the first version in this array that it supports. Later versions in the array are more likely to be deprecated first.

The userMessages/appMessages/appBadges properties indicate which types of push messages the website is allowed to push using the server API.

If the site has been granted permission already and is calling requestURL() again, we can return the same URL without bothering the user.

getCurrentURL() lets the site ask Firefox if the site has a push URL without bothering the user. The function behaves the same way as requestURL() except for the case when requestURL() would prompt the user. I.e. if the user has already granted permission, or if the user has permanently denied permission, then getCurrentURL behaves the same as requestURL. However if the user hasn't yet made a decision, then getCurrentURL results in a success event, but with request.result set to null.

revokeURL() lets the website indicate that it no longer wants to be able to push messages using the indicated URL.

requestURL can fail with either "NetworkError" or "DeniedError"

Simple usage would look like this:

function getPushURL() {
  var push = (navigator.push ||
              navigator.mozPush ||
              navigator.webkitPush);
  // Ask the user to allow notifications
  var request = push.requestURL();
  request.onsuccess = function() {
    var url = request.result.url;
    console.log('Push URL: ' + url);
    // We got a new push URL, store it on the server.
    jQuery.post('/push-urls/', {url: url});
  };
}

If a website wants to display a button which allows the user to start using the push feature for the website, it could do something like this

function displayPushButton(buttonElement) {
  var push = (navigator.push ||
              navigator.mozPush ||
              navigator.webkitPush);
  // Ask the user to allow notifications
  var request = push.getCurrentURL();
  request.onsuccess = function() {
    var result = request.result;
    if (result) {
      // Hide button as we already have the push URL
      buttonElement.hidden = true;
    }
    else {
      // Display button
      buttonElement.hidden = false;
      button.disabled = false;
      button.textContent = "Enable push notifications";
      button.onclick = getPushURL;
    }
  };
  request.onerror = function() {
    if (request.error.name == "DeniedError") {
      // Indicate to user that it's disabled due to user choice
      button.disabled = true;
      button.textContent = "Disabled, change settings to enable";
    }
  }
}

Server API

On the server side we're looking at an HTTP interface that accepts POSTs with these attributes:

type: "userMessage", "appMessage" or "appBadge"
body: Secondary text of the notification. Only relevant for "userMessage" and "appMessage"
iconUrl: URL of the icon to be shown with this notification. Only relevant for "userMessage"
title: Primary text of the notification. Only relevant for "userMessage"
actionUrl: URL to be opened if the user clicks on the notification. Only relevant for "userMessage"
replaceId: A string which identifies a group of like messages. If the user is offline, only the last message with the same replaceId will be sent when the user comes back online. Only relevant for "userMessage"
count: The new badge count for the app. Only relevant for "addBadge"

The format of the payload is still TBD; it's a toss-up between JSON blobs and form-urlencoded parameters.

The server can also issue a DELETE request to the URL to indicate that it no longer wants to send push messages. This is useful for example if the developer accidentally leaked the URL.

HTTP Status Codes in response:

200: Notification accepted for delivery
404: We don't have that URL in our database
410: The user isn't receiving these notifications, e.g. access was revoked

To support bulk sends, we may be able to use SPDY to get longer-lived connections sending a bunch of requests while still keeping the same HTTP interface.

Feedback

(No feedback mechanism is listed, so I'm putting it here; feel free to point me elsewhere :-)

Is the "body" plain text or HTML, or something else?

Are clients forced to support actionURL (the notification system currently used in Ubuntu, for example, specifically removed support for clicking on a notification to take an action)?

What are the rules, if any, about cookie-sending and Referer and Origin when the actionURL is accessed?

Are there maximum lengths for any of the fields?

What about icons of multiple sizes?

Does iconURL lead to a privacy issue because the site can see if the user has read the notification? Can we allow, or require, inline icons?

Are there rules or guidelines to avoid accidentally clashing replaceIDs, such as a "org.mozilla.notification-somerandomstring" convention?

How can we mitigate the problem of one (authorized) site spoofing notifications that look like those from another site? Will the in-browser UI show the origin of the notification?

-- Gerv

Responses

plain text

We can definitely make it optional. I wonder if we should return a set of capabilities along with the URL to let the page know what parts are supported. This will work well when we expand the API to support things like setting "badge numbers" for apps etc.

Setting the Referer to the origin of the site making the request seems like a good idea. Cookies and Origin would be sent as normal (which means that no Origin header is sent).

Yes, we should impose some limit to be determined.

Good question, I don't have a good answer.

Inline icons would be too expensive to push for each notification. One option would be to require that icons are provided when the notification URL is originally requested. That way we could handle multiple sizes too.

replaceIDs are scoped to within the origin, so sites can use whatever scheme they want.

How do we handle this for the Notification API?

-- Sicking

How does this handle a user who uses two different Web browsers? (e.g. IE at work and Firefox at home)

-- Hixie

Responses

UAs should allow setting custom notification services. For example, in Firefox we would by default deliver messages through a Mozilla server, but allow users to choose other notification delivery providers. By choosing the same delivery provider in all browsers, it should be quite possible to make it work. The main problem would be making sure that the delivery provider knows your identity in all browsers, possibly by making you log in when you first set up the service.

-- Sicking

How is the privacy impact of following the user (IP addresses, usage times) reduced to the absolute minimum possible?

Why the middle man Mozilla? Decentralization is a core principle of the Internet.

-- Ben Bucksch

We "only" leak that information to the delivery service. I can't think of a way to allow the delivery service to send messages to the client without knowing the clients address. Suggestions welcome.

Nothing in the API or protocol forces this to go through Mozilla. We can easily let the user choose any delivery service. However we need to go through a delivery service rather than having each website send messages to the device directly in order to reduce IP address/phone number/usage time leakage.

-- Sicking

We don't "need" to go through Mozilla or anybody. When I browse the web, I already contact servers directly and they already see my IP address. Moreover, the server sees every webpage I visit and when. I can only prevent that by using a proxy all the time, but then the proxy can monitor me, and I'd rather avoid that. We have a similar tradeoff here. I argue the sensibility of my Internet usage times is less sensitive than the information which concrete webpages I visit, and the latter already leaks.

This is changing core principles ("decentralization") of the Internet, and I don't see a good justification for that. You are basically forcing a proxy on everybody. If we wanted that, we'd all use HTTP proxies already.

-- Ben Bucksch

From a security viewpoint, the obvious choice to prevent spoofing is digital signatures. However, client-side (in this case the notifying website) developers who aren't familiar with PKI often find it too complex, resulting in a lack of third-party API implementations (see OAuth!). If Mozilla intends to develop, distribute and support the client API themselves, this is less of an issue. If this is not the case, OAuth 2.0 has some non-PKI options. Implementing all of the OAuth 2.0 protocol may be too heavyweight, but it would at least offer some inspiration.

The designers should also consider verifying the integrity and source of notifications received by the browser.

-- Ryan Schipper

WebAPI/PushAPI

Client API

Server API

Feedback