Confirmed users
93
edits
WebAPI/SimplePush: Difference between revisions
Undo revision 640752 by Nikhilm (talk)
| Line 18: | Line 18: | ||
;Endpoint | ;Endpoint | ||
:Unique URL to be used by the AppServer to initiate a response from the App.<br />This is generated by SimplePush and sent to the App. The App will need to relay this to the AppServer. | :Unique URL to be used by the AppServer to initiate a response from the App.<br />This is generated by SimplePush and sent to the App. The App will need to relay this to the AppServer. | ||
;version | |||
SimplePush does not carry information, only versions. A version is a number that keeps increasing. The AppServer tells the Endpoint about a new version whenever it wants an App to be notified. | |||
== Use Cases == | == Use Cases == | ||
<b>An App wishes to be notified when new email arrives</b>. A User installs an <i>App</i> on a mobile device which notifies her when someone adds a note to her bulletin board. The <i>App</i> calls the Registration function, which returns an <i>EndPoint</i>. The <i>App</i> sends the <i>EndPoint</i> to the <i>AppServer</i> using some mechanism not dictated by the protocol. For example, it could use XMLHttpRequest or send an SMS to a special number. The <i>AppServer</i> stores the <i>EndPoint</i> in the User's information. When a new note is added, the <i>AppServer</i> | <b>An App wishes to be notified when new email arrives</b>. A User installs an <i>App</i> on a mobile device which notifies her when someone adds a note to her bulletin board. The <i>App</i> calls the Registration function, which returns an <i>EndPoint</i>. The <i>App</i> sends the <i>EndPoint</i> to the <i>AppServer</i> using some mechanism not dictated by the protocol. For example, it could use XMLHttpRequest or send an SMS to a special number. The <i>AppServer</i> stores the <i>EndPoint</i> in the User's information. When a new note is added, the <i>AppServer</i> fetches the <i>EndPoint</i> and PUTs a new version value to it. The PushServer then notifies the UserAgent, which wakes the <i>App</i> and sends a "push" event. This causes the <i>App</i> to refresh it's messages (again using XHR or some other medium out of the scope of this protocol), and User gets a screen full of adorable kittens. | ||
<b>An AppServer wishes to notify Apps of an update</b>. Since a server doesn't want to be deluged by millions of pings from devices every hour, the developers wisely decide to opt for a Push mechanism. Much like the other example, an <i>App</i> registers with SimplePush, gets an <i>EndPoint</i> which it relays to <i>AppServer</i>. <i>AppServer</i> then PUTs to the <i>EndPoint</i> which triggers a "push" event for the App which then updates itself. | <b>An AppServer wishes to notify Apps of an update</b>. Since a server doesn't want to be deluged by millions of pings from devices every hour, the developers wisely decide to opt for a Push mechanism. Much like the other example, an <i>App</i> registers with SimplePush, gets an <i>EndPoint</i> which it relays to <i>AppServer</i>. <i>AppServer</i> then PUTs a '0' version to the <i>EndPoint</i> which triggers a "push" event for the App, which silently acknowledges that all is well. At some later time, <i>AppServer</i> PUTs '1' to the <i>EndPoint</i> which SimplePush relays to <i>App</i> which then updates itself. | ||
<b>An incoming request from a WebRTC </b>. Bob uses Ringo’s STAR webrtc service. Bob is using the Desktop browser, but the tab/window isn't open to the Ringo service. Alice makes a webrtc call from work to Bob. Bob sees a notification about an incoming call. | <b>An incoming request from a WebRTC </b>. Bob uses Ringo’s STAR webrtc service. Bob is using the Desktop browser, but the tab/window isn't open to the Ringo service. Alice makes a webrtc call from work to Bob. Bob sees a notification about an incoming call. | ||
| Line 83: | Line 86: | ||
} | } | ||
<i>// Once we've registered, the AppServer can send pings to the EndPoint. | <i>// Once we've registered, the AppServer can send version pings to the EndPoint. | ||
// This will trigger a 'push' message to be sent to this handler.</i> | // This will trigger a 'push' message to be sent to this handler.</i> | ||
navigator.mozSetMessageHandler('push', function(message) { | navigator.mozSetMessageHandler('push', function(message) { | ||
if (message.pushEndpoint == emailEndpoint) <i>// Yay! New Email! Steve and blue can dance!</i> | if (message.pushEndpoint == emailEndpoint) <i>// Yay! New Email! Steve and blue can dance!</i> | ||
getNewEmailMessagesFromAppServer(); | getNewEmailMessagesFromAppServer(message.version); | ||
else if (message.pushEndpoint == imEndpoint) <i>// Yay! An IM awaits. I wonder if it's Sam's IM?</i> | else if (message.pushEndpoint == imEndpoint) <i>// Yay! An IM awaits. I wonder if it's Sam's IM?</i> | ||
getNewChatMessagesFromAppServer(); | getNewChatMessagesFromAppServer(); | ||
| Line 113: | Line 116: | ||
=== On the AppServer === | === On the AppServer === | ||
When the application server makes some change to its state, which it feels is important to a certain user, it should use the associated Endpoint to notify the PushServer. For example, when an email server receives a new email whose recipients have MyAmazingEmailApp installed on their devices, every user will have an associated Endpoint. So the server should send a PUT request to every one of those endpoints, with | When the application server makes some change to its state, which it feels is important to a certain user, it should use the associated Endpoint to notify the PushServer. For example, when an email server receives a new email whose recipients have MyAmazingEmailApp installed on their devices, every user will have an associated Endpoint. So the server should send a PUT request to every one of those endpoints, with 'version=<version>' in the body of the HTTP request (that is, as form data). Here is a curl example: | ||
curl -X PUT 'http://mypushserver.com/notificaton/forUserBob' | curl -X PUT --data 'version=5' 'http://mypushserver.com/notificaton/forUserBob' | ||
where 'http://mypushserver.com/notification/forUserBob' is the Endpoint sent by the App. | where 'http://mypushserver.com/notification/forUserBob' is the Endpoint sent by the App. | ||
| Line 121: | Line 124: | ||
'''IMPORTANT NOTE:''' It is very likely that users will install their apps on multiple devices. In this case, each installation of the app has a different Endpoint. You should design your server side storage so that each piece of information may have multiple Endpoints to be notified when it changes. For example, Bob may have MyAmazingEmailApp installed on his Firefox OS phone, he may run it on Firefox for Android and also in his car entertainment system (in some future). In that case, on a new email to Bob, the AppServer should PUT to 3 different endpoints. | '''IMPORTANT NOTE:''' It is very likely that users will install their apps on multiple devices. In this case, each installation of the app has a different Endpoint. You should design your server side storage so that each piece of information may have multiple Endpoints to be notified when it changes. For example, Bob may have MyAmazingEmailApp installed on his Firefox OS phone, he may run it on Firefox for Android and also in his car entertainment system (in some future). In that case, on a new email to Bob, the AppServer should PUT to 3 different endpoints. | ||
curl -X PUT 'http://mypushserver.com/notificaton/forUserBobFirefoxOSDevice' | curl -X PUT --data 'version=5' 'http://mypushserver.com/notificaton/forUserBobFirefoxOSDevice' | ||
curl -X PUT 'http://mypushserver.com/notificaton/forUserBobAndroidFirefox' | curl -X PUT --data 'version=5' 'http://mypushserver.com/notificaton/forUserBobAndroidFirefox' | ||
curl -X PUT 'http://mypushserver.com/notificaton/forUserBobBMWBoombox' | curl -X PUT --data 'version=5' 'http://mypushserver.com/notificaton/forUserBobBMWBoombox' | ||
== DOM Interface == | == DOM Interface == | ||
| Line 137: | Line 140: | ||
<i>// registers to stop receiving push notifications for a given topic | <i>// registers to stop receiving push notifications for a given topic | ||
// DOMRequest.result is | // DOMRequest.result is empty on success.</i> | ||
DOMRequest unregister(DOMString pushEndpoint); | DOMRequest unregister(DOMString pushEndpoint); | ||
<i>// the list of all push registrations for this app | <i>// the list of all push registrations for this app | ||
// DOMRequest.result is an Array of | // DOMRequest.result is an Array of PushRegistration</i> | ||
DOMRequest registrations(); | DOMRequest registrations(); | ||
}; | |||
interface PushRegistration { | |||
<i>// this is the URL to which push notifications from the AppServer | |||
// must be sent to. | |||
// This is how the AppServer alerts the UserAgent that new data exists.</i> | |||
DOMString pushEndpoint; | |||
<i>// undefined when obtained from register().onsuccess | |||
// contains version when obtained from mozSetMessageHandler or registrations().onsuccess</i> | |||
DOMString version; | |||
}; | }; | ||
| Line 161: | Line 175: | ||
[[/Protocol|Protocol]] has the details of how the UserAgent and PushServer communicate. | [[/Protocol|Protocol]] has the details of how the UserAgent and PushServer communicate. | ||
Chances are, all you want is to send a new update. | Chances are, all you want is to send a new version update. | ||
The simplest way to do that is to call | The simplest way to do that is to call | ||
POST <i>endpoint</i> | |||
version=<i>newversion</i> | |||
Where <i>endpoint</i> is the value that was returned during App's registration. | Where <i>endpoint</i> is the value that was returned during App's registration. | ||