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();

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

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

interface PushRegistration {
  // 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 channelID;
};

interface PushEvent : Event {
  // this is topic string used when registering for push notifications 
  DOMString channelID;

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

Client Example

App manifest

{
  ...
  "permissions": {
    ...
    "push": {
      "description": "Check for new mail"
    }
  },
  "messages": [
    {"notification": "/view_to_launch.html"}
    {"notification-register": "/view_to_launch.html"}
  ]
}

JavaScript

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

// apps can do something like
// This handler may be triggered *immediately* after mozSetMessageHandler is called
// so applications should ensure they are ready (UI created, state loaded etc.)
navigator.mozSetMessageHandler('push', {
  handleMessage: function(e) {
    if (e.type == 'register-again')
      // re-issue register() calls
    else if (e.type == 'update') {
      e.channelID == 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
navigator.pushNotifications.register();


// success callback
navigator.onregistered = function(e) {
  // post to application server
  e.target.result.pushEndpoint
  e.target.result.channelID
}

navigator.onerror = function(e) {
  e.type == 'registration-failed' or e.type == 'unregistration-failed'
  e.channelID set in case of unregistration
}

// to unregister, you simply call..

navigator.pushNotifications.unregister(channelID);
navigator.onunregistered = function(e) {
  // post to app-server
}

Server API

Definitions

UserAgent

The client acting on behalf of the user and consumer of update notices

UAID

A server generated, globally unique UserAgent ID

PushServer

The server managing interactions between AppServers and the UserAgent

AppServer

The third party publisher of update notices

Channel

The flow of information from AppServer through PushServer to UserAgent

ChannelID

Globally Unique identifier for a Channel

UserAgent and AppServer will use a RESTful API to interact with the Push Server.

API

• Requests from UserAgent to PushServer MUST provide a PushServer Generated UserAgentID (UAID) as the "X-UserAgent-ID" header.
• UserAgent requests may include a /{network} prefix to indicate a request may be handled by a third party network (e.g. GET http:host/foonet/update will return update requests for elements provided by the "foonet" sub-provider.
• Calls will return standard HTTP status headers.
• Calls will return status 200 (unless otherwise noted below).
• On Errors, calls will return a proper error code, and where permitted, a standard JSON block containing information regarding the error. The contents of this block are not intended for end user display and have yet to be finalized.

GET /register

Request a new ChannelID.

If the X-UserAgent-ID is not provided, the UserAgent is presumed to be new and a new UserAgentID will be generated for the UserAgent.

Arguments

No additional arguments are required.

Returns

{ "channelID": "New Channel ID", 
  "uaid": "UserAgent ID"
}

NOTE: The uaid is either the X-UserAgent-ID value echoed back, or a new X-UserAgent-ID value to be used for all subsequent calls if no X-UserAgent-ID was present.

Example

GET http://push.m.o/register 
---
{"channelID": "foo1234", "uaid": "bar5678"}

DELETE /<ChannelID>

Delete an associated ChannelID. Subsequent calls to this ChannelID will result in a 404 status.

NOTE: the X-UserAgent-ID Header must be present and match the one associated with this ChannelID

Arguments

There are no arguments for this call.

Returns

This returns an empty JSON object

{}

Example

DELETE http://push.m.o/unregister/foo1234
---
{}

GET /update

Return a list of known ChannelIDs and current versions.

NOTE: the X-UserAgent-ID must be provided and match the value returned by the /register call.

Arguments

There are no arguments for this call.

Returns

This will return a hash containing a list of hashes defining the known, associated Channels and versions.

NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410. See POST /update for details.

Example

GET http://push.m.o/update
---
{"channels":[{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},{"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}]}

POST /update

Refresh the server from the client.

This request requires a X-UserAgent-ID header. If the UserAgent attempts to POST information to the server which already has data for that X-UserAgent-ID, the server will deny the request with a 403 error. In that case, the UserAgent should request re-registration for all Channels.

1. Server state MUST be considered the canonical state, unless the server has NO state.
2. On an /update call, the server MUST atomically update its state.

Arguments

The POST body is a JSON encoded block which matches the form and structure of the GET /update/ request.

Returns

This will return an empty object.

Example

POST http://push.m.o/update
{"channels":[{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},{"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}]}

---
{}

PUT /update/<ChannelID>

Update the version of a given channel.

Arguments should be passed as standard form data (enctype: multipart/form-data) This call does not require a X-UserAgent-ID, as it may be called by the AppServer.

Arguments

version=<version>

The version is the AppServer specific VersionID to use. This ID is opaque to the PushServer, however it is suggested that:

• The ID be sequential.
• The ID be less than 100 characters.
• The ID should be UTF8 compliant.

Returns

This call returns an empty JSON object.

Example

PUT http://push.m.o/update/foo1234
version=1.3
--- 
{}