WebAPI/SimplePush

Client Side API

partial interface Navigator {
  PushNotification pushNotification;
};

interface PushNotification : EventTarget {

  // registers to receive push notifications for a given topic
  // DOMRequest.result is a PushRegistration in case of success
  DOMRequest register(DOMString topic);

  // registers to stop receiving push notifications for a given topic 
  // DOMRequest.result is a PushRegistration in case of success
  DOMRequest unregister(DOMString topic);

  // returns the list of all push registrations for this origin
  PushRegistration[] registered();

  // event MUST be of type PushEvent
  attribute EventHandler onmessage;
};

interface PushRegistration {

  // this is the string that was used when calling register()
  DOMString topic;

  // this is the URL to which push notifications from the web application
  // must be sent to.
  // application should send this and pushRequestID as a pair to the
  // application server
  DOMString pushEndpoint;

  // this is the push request id that must be sent to the push server with
  // every push notification update
  DOMString pushRequestID;

};

interface PushEvent : Event {

  // this is topic string used when registering for push notifications 
  DOMString topic;

  // this is the most current version 
  unsigned long long version;
}

Client Example

// all notifications will be sent to the system message handler.
// which is up to the U/A to implement

// apps can do something like
navigator.pushNotification.onmessage = function(e) {
  e.topic == This is the topic that is being observed
  e.version == This is the current version for this topic
});


// to register to listen for a notification,
// you simply call push.register and pass a
// topic of interest:

var req = navigator.pushNotifications.register("topic");


// success callback
req.onsuccess(e) = function() {
  // post to application server
  e.target.result.pushEndpoint
  e.target.result.pushRequestID
}

req.onerror() = function(e) {}

// to unregister, you simply call..

req = navigator.pushNotifications.unregister("topic");
req.onsuccess() = function() {}
req.onerror() = function() {}

Server API

We will use a RESTful API to interact with the Push Server.

The Push Server URL is returned to the client as a result of calling register(). The pushEndpoint is the URL to the Push Server.

Successful calls will return HTTP Status 200 with new content or 204 with no update change

Unless otherwise noted the following HTTP error codes:

401

Authorization failure

404

pushRequestID not found

500

Server error.

Registering with Push Server

POST pushEndpoint/register/[<network>/]<pushRequestID>

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().

These query parameters are optional with each registration:

• Network Association
  • network
  • This may be a identification string that represents where the the client can also be reached at.
  • We need some way to say this client can be notified on another network (via UDP instead of a long poll)
  • For example network = "telefonica"

Example:

  POST http://push.mozilla.org/register/telefonica/<pushRequestID>

If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:

// tbd
{
  "result": {}
}

Un-registering with Push Server

DELETE pushEndpoint/register/[<network>/]<pushRequestID>

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().

Example:

  DELETE http://push.mozilla.org/register/telephonica/<pushRequestID>

If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:

// tbd
{
  "result": {}
}

Client check for updates

GET pushEndpoint/update/[<network>/]<pushRequestID>?version=<lastPulledVersion>

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().

• network
  • Optional network specifier.

Example:

GET <i>pushEndpoint</i>/update/telephonica/<pushRequestID>?version=12345

Returns:

200 Success

{
   "result": {"update": <newVersionNumber>}
}

204 Success (No content, no change in version.)

{
   "result": {}
}

Notify Push Server of a new version

PUT pushEndpoint/update/<network>/<pushRequestID>?version=<version>

These query parameters are required with each update:

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().
• Version
  • version is the query parameter name.
  • The value of version is the most current version number of the object referenced by pushRequestID

Example:

  PUT http://push.mozilla.org/update/<pushRequestID>?version=<version>

If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:

{
  "result": {}
}

Simple event flow

    +---------------+                 +-----------------+              +------------------+
    |   Browser     |                 |   Push Server   |              |    App Server    |
    +------+--------+                 +--------+--------+              +---------+--------+
           |           register()              |                                 |
           +---------------------------------->|                                 |
           |                                   |                                 |
           |           ok                      |                                 |
           |<---------------------------------+|                                 |
           |                                   |                                 |
           |           register successful     |                                 |
           |+------------------------------------------------------------------->|
           |                                   |                                 |
           |                                   |        Update                   |
           |                                   | <-------------------------------+
           |                                   |        Update                   |
           |                                   | <-------------------------------+
           |           update                  |                                 |
           |<----------------------------------+                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |
           |                                   |                                 |