WebAPI/PushAPI

Mozilla has no plans on implementing this. Please see WebAPI/SimplePush instead.

This page is for historical purposes only.

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. Code is in Github

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 strongly suggested that this be a minimally 256bit random, base64 value or equivalent in order to reduce potential collisions. WATokens are limited to 45 URL safe characters.

publicKey
used to verify the origin of the notification. This is a cryptographic key generated by the AppProvider 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

Push Notification Messages are sent to the url returned by the Client API requestURL() response (NotificationURL). Notification content consist of a JSON block POSTed to the NotificationURL

Notification JSON Content

The Push Notification JSON block consists of the following:

• messageType: "notification". 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
• id: a server side generated id to identify the notification. Mandatory.
• message: Main body. This could contain a maximum of 1024 bytes. Can be anything that fits in UTF8. Optional
• 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. In seconds. Optional.
• timestamp: Time when the notification was sent. In seconds. Optional.
• priority: A priority value, from 1 to 4. 1 should be delivered instantly, and 4 will be delivered at the servers discretion. Optional

Response

HTTP Status Codes in response:

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

Error Response Body

When the notification is rejected, the NotificationURL server will return a JSON block with the following content:

• status: 'ERROR'
• reason: Reason the Status post failed to be handled. Optional