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, publicKey)

asks the user if they'd like to allow the app requesting to send notifications. If the app has been granted permission already and is calling requestURL() again, the original values are returned and no user interaction is required.

Arguments

WAToken
the Web App Token identifies uniquely the user (or installation) of the app (or a shared WAToken, used for broadcast). It is generated by XXX

publicKey
used to verify the origin of the notification. This is a cryptographic key generated by the app and should be unique per user.

Returns

request.result will be a "JSON object" with the following structure

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

status
"SUCCESS" on successful registration of WAToken, otherwise, "ERROR".

SUCCESS parameters

url
returns the URL the app server may use to send a Push Notification messages to the user.

messageType
registeredWA response to this message

WAToken
same value as the WAToken parameter

Error parameters

reason
Optional value which may contain a more explicit message error.

WAtoken
same value as the WAToken parameter

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.

Arguments

There are no arguments for this function

Returns

This function returns the stored values for requestURL() or Null if no stored values exist.

revokeURL(url)

lets the app indicate that it no longer wants to be able to push messages using the indicated URL for this installation.

Arguments

url
The URL returned by a previously successful requestURL() call.

Examples

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.