Chapter 3. Notification server API

This API is mainly based on the W3C draft as specified in [http://dvcs.w3.org/hg/push/raw-file/default/index.html]

Also there is more information about Simple PUSH API here: [https://wiki.mozilla.org/WebAPI/SimplePush]

With this API the application is able to register notification channels itself into the Notification Server and recover the public URL to be used as the notification endpointURL by his Application Server (AS).

This API (under the navigator.push object) defines these methods:

        
        navigator.push.register()
        
        

        
        var req = navigator.push.register();
        req.onsuccess = function(e) {
          alert("Received URL: " + req.result.pushEndpoint);
        };
        req.onerror = function(e) {
          alert("Error registering app");
        }
        
      

        
        navigator.push.unregister(endPointURL);
        
      

After register the application into the Notification Server, all received notification through the given URL will be delivered to the WA registered channel.

Since the notifications will be received by the UA it's needed a way to notify each application. The current specification is using the new System Messages infrastructure defined in FirefoxOS.

In this case, the application shall register to the "push-notification" event handler:

    
    navigator.mozSetMessageHandler("push", function(msg) {
      alert("New Message with body: " + JSON.stringify(msg));
    });
    
    

Inside the msg you'll receive the pushEndpoint URL so an app can register as many channels as it wants and with this attribute has a chance to differenciate one from another.

The complete example:

      
        var emailEndpoint, imEndpoint;

        // The user has logged in, now's a good time to register the channels
        MyAppFramework.addEventListener('user-login', function() {
          setupAppRegistrations();
        });

        function setupAppRegistrations() {
         // Issue a register() call
         // to register to listen for a notification,
         // you simply call push.register
         // Here, we'll register a channel for "email" updates.
         // Channels can be for anything the app would like to get notifications for.
         var reqEmail = navigator.push.register();
         reqEmail.onsuccess = function(e) {
           emailEndpoint = e.target.result.pushEndpoint;
           storeOnAppServer("email", emailEndpoint); // This is the "Hand wavey" way that the App 
                                                     // sends the endPoint back to the AppServer
         }

         // We'll also register a second channel for "im", because we're social and all about the socialists. Or something.
         var reqIm = navigator.push.register();
         reqIm.onsuccess = function(e) {
           imEndpoint = e.target.result.pushEndpoint;
           storeOnAppServer("im", imEndpoint);
         }
        }

        // 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.
        navigator.mozSetMessageHandler('push', function handlePushMessage(message) {
          if (message.pushEndpoint == emailEndpoint)   // Yay! New Email! Steve and blue can dance!
            getNewEmailMessagesFromAppServer(message.version);
          else if (message.pushEndpoint == imEndpoint) // Yay! An IM awaits. I wonder if it's Sam's IM?
            getNewChatMessagesFromAppServer();
        });

        // to unregister, you simply call..
        AppFramework.addEventListener('user-logout', function() {
          navigator.push.unregister(emailEndpoint);
          navigator.push.unregister(imEndpoint);
        });