Confirmed users
93
edits
WebAPI/SimplePush: Difference between revisions
Jump to navigation
Jump to search
Remove mention of version from web facing API
No edit summary |
(Remove mention of version from web facing API) |
||
| 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. | ||
== 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> notifies the <i>EndPoint</i> by PUTting an empty request 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 | <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 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 86: | Line 83: | ||
} | } | ||
<i>// Once we've registered, the AppServer can send | <i>// Once we've registered, the AppServer can send 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(); | ||
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 116: | Line 113: | ||
=== 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 an empty body. Here is a curl example: | ||
curl -X PUT | curl -X PUT '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 124: | Line 121: | ||
'''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 | curl -X PUT 'http://mypushserver.com/notificaton/forUserBobFirefoxOSDevice' | ||
curl -X PUT | curl -X PUT 'http://mypushserver.com/notificaton/forUserBobAndroidFirefox' | ||
curl -X PUT | curl -X PUT 'http://mypushserver.com/notificaton/forUserBobBMWBoombox' | ||
== DOM Interface == | == DOM Interface == | ||
| Line 140: | Line 137: | ||
<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 the endpoint that was unregistered 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 EndPoints as DOMStrings</i> | ||
DOMRequest registrations(); | DOMRequest registrations(); | ||
}; | }; | ||
| Line 175: | Line 161: | ||
[[/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 | Chances are, all you want is to send a new update. | ||
The simplest way to do that is to call | The simplest way to do that is to call | ||
PUT <i>endpoint</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. | ||