WebAPI/SimplePush/Protocol

[Work In Progress]

The following are SimplePush hoo-doo things that are probably not important to you. Here, look at this device while I put on my sunglasses.

Channel

The flow of information from AppServer through PushServer to UserAgent.

ChannelID

Unique identifier for a Channel. Generated by UserAgent for a particular application.

UAID

A globally unique UserAgent ID

Index

 NOTIFICATION DESKTOP NOTIFICATION GROUPS MANAGEMENT

Urls - More info

https://wiki.mozilla.org/WebAPI/SimplePush http://www.w3.org/TR/push-api/

http://frsela.github.com/notification_server_doc/

https://github.com/acperez/mozilla-central/blob/push-client-netwerk-server-socket/dom/push/src/PushNotificationService.js#L642 https://github.com/frsela/pushJSlibrary/blob/master/library/push.js https://github.com/telefonicaid/notification_server

http://www.youtube.com/watch?v=s6tOZdPYda8&feature=youtu.be

�

API Push Client - Push Server

This should be considered a translation to WebSockets of the API defined here - https://wiki.mozilla.org/WebAPI/SimplePush/ServerAPI Status/Error codes documented in that document apply here unless explicitly marked otherwise.

Push API endpoint for WebSocket connection is : wss://push.server.com/v1/

C->S:

           {
     		messageType: "hello",
       		uaid: "<a valid UAID>",

channelIDs: [channelID1, channelID2, …],

       		interface: {

ip: "<current device IP address>",

         			port: "<TCP or UDP port in which the device is waiting for wake up notifications>"
},
mobilenetwork: {

mcc: "<Mobile Country Code>", mnc: "<Mobile Network Code>"

},

protocol: <wakeup protocol. OPTIONAL. By default: UDP>

   	}

uaid can be null, then, a new uaid is created (see next)

S->C:

{ messageType: “hello”, status: xxx, <200, ...>, uaid: <if not provided by previous call, a new valid one will be generated> }

NOTE: All pending registration/unregistration requests stay on ‘hold’ until the client has transmitted new state and the server has concurred.

Recovery protocol

The client “hello” contains the “uaid” field. If the “uaid” field is known by the server, the server should check that the list of channelIDs sent by the client matches what it has. If there is even a single channelID that the server does not know about, it should generate a new UAID for the client, and drop all state about the current UAID. This will cause the client to generate new channelIDs by waking up all apps and having them register. This way apps get latest state since they contact their server.

If the server has ‘extra’ channelIDs associated with the UAID, it can simply delete them. Channel Registration:

A client channel registration request:

  	{
     		messageType: "register",

channelID: "<ChannelID>

   	}
   	

The server response can be:

{ messageType: “register”, status: xxx, pushEndpoint: <pushendpoint>, channelID: <channelId> }

Channel Deletion:

{

     		messageType: "unregister",
     		channelID: <channelId>
   	}

The server response can be:

{

     		messageType: "unregister",

status: xxx,

     		channelID: <channelId>
   	}

Channel Update:

Server -> Client { messageType: “notification”, updates: [{"channelID": "id", "version": "XXX"}, ...] }

Client -> Server { messageType: “ack”, updates: [{"channelID": channelID, “version”: xxx}, ...] } API Application Server - Notification Server

NOTIFICATION

https://server:port/notify/<hashed channelID> [Actually Opaque as far as anyone other than the push server is concerned]

Method PUT Payload:

version=<version>

April Discussion Below:

DESKTOP NOTIFICATION

https://server:port/notify/<hashed channelID>

Method PUT Payload:

body=<any text>[&ttl=<ttl>]

GROUPS MANAGEMENT [WIP]

https://server:port/groups

CRUD API: C: POST https://server:port/groups Returns URL (pushEndpoint)

R: GET https://pushEndpoint Returns: [endPointURL1, endPointURL2, …]

U: PUT https://pushEndpoint url=endPointURLN&op=[ADD|DELETE] Returns: 200 OK or 404 No group found

D: DELETE https://pushEndpoint Removes the group Returns: 200 OK or 404 No group found

�

WAKEUP API [WIP]

This (WIP) API will be offered by the carriers in order to be able to wakeup handsets inside their own mobile networks.

Connection to this API will be protected with client certificates signed by the carrier so only trusted 3rd. party notification servers will be able to send datagrams to the handsets.

https://server:port/wakeup

GET mcc=<mcc>&mnc=<mnc> RETURNS 200 OK (We’ve a wake up server in that network !) 404 Error (We don’t have a wake up server)

PUT ip=<ip>&port=<port>&mcc=<mcc>&mnc=<mnc> RETURNS 200 OK

�

Channel Update:

Server -> Client { messageType: “notification”, updates: [{"channelID": "id", "version": "XXX"}, ...] }

{

     		messageType: "desktopNotification",

updates: [{"channelID": "version", _internal_id: ..., "body": "body"}, ...]

   	}

Return Status codes

WIP: https://github.com/telefonicaid/notification_server/blob/mozAPI/src/common/constants.js nikhil: I think you’ll just want to use the ones from the mozilla spec that are required, like 404 and so on. Most of the other status codes are not required in my opinion.