WebAPI/PushAPI

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 so we want to develop it to FirefoxOS.

Status

Server side

This is being implemented by User:willyaranda and User:frsela at Telefónica.

Gecko implementation

User:Thinker has implemented the Gecko side.

Bug #763198 is the implementation bug.

Bug#776501 is the security bug.

Client API

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

interface PushManager {
  DOMRequest requestURL(jsval watoken, jsval PbK);
  DOMRequest getCurrentURL();
  DOMRequest revokeURL(jsval URL);
}

requestURL(watoken, PbK) asks the user if they'd like to allow the app requesting to send notifications. It requires two arguments, a "watoken" that identifies uniquely the user (or installation) of the app (or a shared watoken, used for broadcast) and the app public key, that will be used to verify the origin of the notification.

When the success callback runs, request.result will be a "JSON object" with the following structure

dictionary PushURLResult {
  DOMString status;
  DOMString reason?;
  DOMString url?;
  DOMString messageType;
  DOMString WAtoken;
}

The status property says if the registration of a given WA token is correct or not:

• a ERROR status is sent, then, the reason could contain a more explicit message error.
• a SUCCESS status is sent when it's correct. Then, the field url is defined.

The reason is only defined if the status field (shown above) is ERROR. Not mandatory.

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

The messageType is registerWA which is the response to this kind of messages.

The WAtoken is the app token that was used to register. This can be used by the user agent to identify what URL belongs to a specified token or if there is some error.

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

getCurrentURL() lets the app ask Firefox if the app 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(url) lets the app indicate that it no longer wants to be able to push messages using the indicated URL for this installation.

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(watoken, PbK);
  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 a JSON POST with these attributes:

• messageType: "notification". Mandatory
• id: a server side generated id to identify the notification. Not mandatory.
• message: Main body. This could contain a maximum of 1024 bytes. Can be anything that fits in UTF8. Mandatory
• signature: The text message signed with the Private Key that is verified and, if fails, the notification is thrown away and not accepted. Mandatory
• ttl: Maximum time of live of the notification. The server will discard any notification in a maximum time or in the ttl time, whatever first occurs. Not mandatory.
• timestamp: Time when the notification was sent. Not mandatory.
• priority: A priority value, from 1 to 4. 1 should be delivered instantly, and 4 co

HTTP Status Codes in response:

• 200: Notification accepted for delivery
• 400: Notification rejected.

HTTP Body response:

When received a 400, there is a JSON with the status ERROR and a possible reason.