WebAPI/SimplePush: Difference between revisions

Jump to navigation Jump to search

WebAPI/SimplePush (view source)

Revision as of 18:22, 6 March 2013

708 bytes added ,  6 March 2013
no edit summary
No edit summary
Line 1: Line 1:
You're a service. Getting clients to talk to you is pretty easy. All you have to do is sit there and wait for them to call. But, what if you want to tell your clients that there's something interesting for them?
SimplePush is a way for application developers to send messages to their web applications. Rather than have applications continuously poll your server for the latest information, you can take advantage of the SimplePush API. This is a very low cost service that let's servers tell clients "Hey, there's something interesting over here! You ought to do something about that."
 
SimplePush is a very low cost service that let's servers tell clients "Hey, there's something interesting over here! You ought to do something about that."


== Definitions ==
== Definitions ==
Line 10: Line 8:


;AppServer
;AppServer
:The third party publisher of update notices.<br />This is, more than likely, where all the real work of your App is done. It's what has the mail, or the articles, or where someone whacks serpents with farm implements for slices of virtual dessert.  
:The third party publisher of update notices.<br />This is your application (mail/chat/calendar) server. This is, more than likely, where all the real work of your App is done. It's what has the mail, or the articles, or where someone whacks serpents with farm implements for slices of virtual desert.  


;UserAgent
;UserAgent
Line 16: Line 14:


;PushServer
;PushServer
:The server managing interactions between AppServers and the UserAgent.<br />This is what the AppServer is talking to when it wants to tickle the client.  
:The server managing interactions between AppServers and the UserAgent.<br />This is what the AppServer is talking to when it wants to tickle the client. This is managed by a third party, and you, the app developer, doesn't worry about it.


;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.




Line 32: Line 33:
;UAID
;UAID
:A globally unique UserAgent ID
:A globally unique UserAgent ID
UserAgent and AppServer will use a RESTful API to interact with the Push Server.


== 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 the magic of "Not-Part-Of-This-Protocol". 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. This alerts SimplePush, which wakes the <i>App</i> and sends a "push" event. This causes the <i>App</i> to refresh it's messages (again using the magical "Not-Part-Of-This-Protocol" system), and User gets a screen full of adorable kittens.
<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 a '000' 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 '001' to the <i>EndPoint</i> which SimplePush relays to <i>App</i> which then updates itself using "Not-Part-Of-This-Protocol-Either".
<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 58: Line 56:
=== Client Side API ===
=== Client Side API ===


Apps will need to add the following to their manifests. See our Web App Development Guide for what this means and how to use it.
==== For App developers ====
==== App manifest ====
 
Apps will need to add the following to their [https://developer.mozilla.org/en-US/docs/Apps/Manifest manifest]. See our Web App Development Guide for what this means and how to use it.
 
  {
  {
   ...
   "permissions": {
    "push": {"description": "To receive notifications about the newest phone releases"}
  },
   "messages": [
   "messages": [
     {"push": "/view_to_launch.html"}
     {"push": "/view_to_launch.html"}
     {"push-register": "/view_to_launch.html"}
     {"push-register": "/view_to_launch.html"}
   ]
   ]
  }  
  }
==== JavaScript ====
 
We've tried to make the client code as simple as possible. While the following may not be what you use, it shows the general idea.
Websites are likely to present a doorhanger to the user the first time they attempt to use the push notification API. The user experience on Firefox Desktop has not been drawn out yet.
 
We've tried to make the client code as simple as possible. While the following may not be what you use, it shows the general idea. This code will be in view_to_launch.html.


  var emailEndpoint, imEndpoint;
  var emailEndpoint, imEndpoint;
<i>// The user has logged in, now's a good time to register the channels</i>
MyAppFramework.addEventListener('user-login', function() {
  setupAppRegistrations();
});
   
   
  function setupAppRegistrations() {
  function setupAppRegistrations() {
Line 76: Line 85:
   // to register to listen for a notification,
   // to register to listen for a notification,
   // you simply call push.register
   // you simply call push.register
   // Here, we'll register a channel for "email" updates. Channels can be for anything the app would like.</i>
   // Here, we'll register a channel for "email" updates.
  // Channels can be for anything the app would like to get notifications for.</i>
   var reqEmail = navigator.pushNotification.register();
   var reqEmail = navigator.pushNotification.register();
   reqEmail.onsuccess = function(e) {
   reqEmail.onsuccess = function(e) {
     emailEndpoint = e.target.result.pushEndpoint;
     emailEndpoint = e.target.result.pushEndpoint;
     storeOnAppServer("email", emailEndpoint); <i>// This is the "Hand wavey" way that the app
     storeOnAppServer("email", emailEndpoint); <i>// This is the "Hand wavey" way that the App
                                                 // sends the endPoint back to the server</i>
                                                 // sends the endPoint back to the AppServer</i>
   }
   }
   
   
Line 99: Line 109:
       getNewEmailMessagesFromAppServer(message.version);
       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(message.version);
       getNewChatMessagesFromAppServer();
   }
   }
});
<i>// The user has logged in, now's a good time to register the channels</i>
AppFramework.addEventListener('user-login', function() {
  setupAppRegistrations();
  });
  });
   
   
Line 129: Line 134:
  });
  });


==== Interface ====
==== DOM Interface ====
  partial interface Navigator {
  partial interface Navigator {
   PushNotification pushNotification;
   PushNotification pushNotification;
Line 155: Line 160:
   DOMString pushEndpoint;
   DOMString pushEndpoint;
   
   
   <i>// undefined when obtained from register().onsuccess.
   <i>// undefined when obtained from register().onsuccess
   // contains version when obtained from PushEvent</i>
   // contains version when obtained from mozSetMessageHandler or registrations().onsuccess</i>
   DOMString version;
   DOMString version;
  };
  };
interface PushEvent : Event {
  PushRegistration target;
}


==== Notes ====
==== Notes ====
Nikhilm
Confirmed users
93

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/537436"

Navigation menu