ATTENTION: OLD DOCS

This document is an old version of the PushAPI. This is updated by WebAPI/PushAPI.

OLD DOC

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.

Status

The server API needs to be verified by someone that knows server-infrastructure better than me.

We should also verify this API against the experiences from Google here: [1]

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

Please put feedback on the Talk Page