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.

Registering with Push Server

pushEndpoint/register

These query parameters are required with each registration:

• API Key
  • TBD
  • key is the query parameter name
• pushRequestID
  • pushRequestID is the query parameter name.
  • 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=telefica"

Example:

  POST http://push.mozilla.org/register?key=<apikey>&pushRequestID=<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

pushEndpoint/unregister

These query parameters are required with each un-registration:

• API Key
  • TBD
  • key is the query parameter name
• pushRequestID
  • pushRequestID is the query parameter name.
  • The value of pushRequestID must be the result returned to the client as a result of calling register().

Example:

  POST http://push.mozilla.org/unregister?key=<apikey>&pushRequestID=<pushRequestID>

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

// tbd
{
  "result": {}
}

Notify Push Server of a new version

pushEndpoint/update

These query parameters are required with each un-registration:

• API Key
  • TBD
  • key is the query parameter name
• pushRequestID
  • pushRequestID is the query parameter name.
  • 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:

  POST http://push.mozilla.org/update?key=<apikey>&pushRequestID=<pushRequestID>&version=<version>

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

// tbd
{
  "result": {}
}

Simple event flow

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