Historically mobile operators offered (and offer) real mechanisms PUSH notifications, also known as WAP PUSH. WAP PUSH can "wake up" applications when any action is required of them by the server side (without interaction from the user). Sending WAP PUSH messages is done in the domain of circuits, the same used for voice and SMS, and that is why the user don't need to establish a data connection. These kind messages work properly out of the box.

WAP PUSH solutions works great when the user is registered in the mobile network, but if you are out of coverage or connected to a WiFi hotspot instead a celular network, you can not receive these messages.

Also, if we add that this messages implies an economic cost (basically it is a short message SMS) the effect is that major smartphone operating systems (Apple iOS and Google Android) have implemented a parallel solution that would work regardless of the mobile network to which the user belongs and it can run smoothly when they are using WiFi networks.

The Notification Server platform is aimed to deliver push notifications (small messages like a real-time chat, a JSON data structure defining the goal of a soccer match) to web based terminals inside mobile networks.

The main objective of this service is to deliver these messages considering the way of working of the mobile radio so the battery consumption and traffic generated is reduced to the minimal. It is developed for working on stable Internet connections, like on Wi-Fi or Ethernet.

Since we want a service to be used, we think it to be very easy to use and to be great for developers.

Now, we point out some adventages with the use of this solution:

Since on IPv4 the amount of free adresses is really low, celular networks were divided into the ones with real IPv4 adresses (normally for 3G modems) and private adressing model for handsets.

On the case of private networks, it's obvious that it's not possible to directly notify the handset when the server has a notification for it, so smartphone manufacturers decided to maintain opened channels with their servers so it's possible to notify handsets asynchronously.

On the other hand, if the handset has a public address, or is using IPv6, it's teorically possible to send the message directly making third party solutions unuseful, however in order to protect users, carriers can deploy firewalls to avoid direct access from Internet to the handset.

In the 3GPP TS 25.331 specification, we can query all the circuit domain statues of the RRC Layer (Radio Resource Control).

In order to simplify, we only list the third generation (3G) states:

The following scheme represent the different radio states ordered by power comsuption on the device:

In the 3GPP TS 23.060 specification, we can analyse all the package domain states of the GMM Layer (GPRS Mobility Management).

The package domain states are simpler than radio ones (only 3 states):

In this section we show the relation between RRC and GMM states.

In order to simplify this table, we only consider the handset is only using data channels, so no voice nor SMS (circuit domain) is being used.

This is a carrier well-know effect after the big adoption of smartphones around the word.

As we explained in previous sections, each time the network decides to move a handset from one state to another is needed to restablish channels and starts a negotiation between the network and the handset with the signalling protocol.

Since nowadays handsets are sending keep-alives to maintain their connections opened, the efect is that the handsets is continously changing from one state to another producing a lot of signalling in the network and also consumes a lot of battery resources.

The battery comsuption depends on the Radio state. The following list represent the amount of battery needed on each state represented in relative units:

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);
        });
      
    

With this API the client device is able to register his applications and itself into the selected notification server.

This API isn't yet standarised, anyway the one explained here is an on working proposal.

The UA-NS API is divided in two transport protocols:

      
      kill -SIGUSR1 <pid>
      
    

      
      kill -SIGUSR2 <pid>
      
    

WebSocket API

Through this channel the device will register itself, his applications, and also will be used to deliver PUSH notifications

The websocket API supports multiple subprotocols identified each one with it's name:

• push-notification

  Simple protocol defined by Mozilla and Telefonica and described here: [https://wiki.mozilla.org/WebAPI/SimplePush/Protocol] .

• push-notification-binary

  Binary version of the push-notification protocol

• push-extended-notification

  Telefonica extended solution which provides more functionalities

WebSocket: push-notification

Also know as "Simple push protocol" and defined by Mozilla and Telefonica.

This protocol is based in the Thialfi protocol . described by Google.

Also you can read more about this protocol in the Mozilla Wiki: [https://wiki.mozilla.org/WebAPI/SimplePush/Protocol] .

In order to use this subprotocol, the "push-notification" string shall be sent into the websocket handsake headers.

All methods sent through this channel will have the same JSON structure:

  
  {
    messageType: "<type of message>",
    ... other data ...
  }
  
  

In which messageType defines one of these commands:

hello

With this method the device is able to register itself.

The device is responsible to give the server a valid UAID. If the provided UAID is not valid or is "null", the server will respond with a valid one.

In next connections the UAID given by the server SHALL be used.

When a device is registering to a notification server, it SHALL send his own valid UAID and also the device can send additional information that can be used to optimize the way the messages will be delivered to this device.

If it's not the first connection, the device can send a list of registered channels in order to syncronize client and server data. This mechanism allows a way to recover channels after a server crash.

    
    {
      messageType: "hello",
      uaid: "<a valid UAToken>",
      channelIDs: [<a list of channels to sync [OPTIONAL]>],
      wakeup_hostport: {
        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>"
      }
    }
    
    

The wakeup_hostport and mobilenetwork optional data will be used by the server to identify if it has the required infrastructure into the user's mobile network in order to send wakeup messages to the IP and port indicated in the wakeup_hostport data so it's able to close the WebSocket channel to reduce signalling and battery consume.

The channelIDs array is sent by the client in order to synchronize server and client.

When the server receives a new hello message and the UAID provided by the client is a valid one (in other words, is the same returned to the client) the channelIDs list will be used to syncronize the server information with the client one.

For example, after a server crash, all client channels will be recovered with this simple method.

Another example, if the client uninstalled an app when the handset was offline, next time it connects will send tne channel list with one less, so the server will unregister this channel.

The server response can be one of these:

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

if it's connected through a permanent websocket, or:

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

if it's connected to a wakeup channel (UDP).

Note

This hello response differenciation is pending to change in order to use Websocket close status: on this Github Pull Request .

      
      {
        messageType: "hello",
        status: 4xx,
        reason: "<any reason>"
      }
      
      

on any error case, like:

• 460: Error registering UAID

This method is also used to anounce a new IP address or a network change.

register

This method is used to register push channels. Each application can register as many channels as it wants. Each channel maintains an independent counter about the last version of the channel.

This shall be send to the notification server after a valid UA registration.

Normally, this method will be used each time an application requires a new channel to receive Thialfi like notifications. A new endpoint URL will be delivered (through the WA-UA API).

No data is required at application level, only the UA client is responsible to generate a unique channelID for the handset. The channelID can be the same in different devices since the UAID will be used in the endpoint URL hash.

    
    {
      messageType: "register",
      channelID: "<a new channelID>"
    }
    
    

The server response can be:

      
      {
        messageType: "register",
        status: 200,
        pushEndpoint: "<publicURL required to send notifications>",
        channelID: "<the channelID>"
      }
      
      

      
      {
        messageType: "register",
        status: 4xx,
        reason: "<any reason>"
      }
      
      

on any error case, like:

• 457: Not valid channelID
• 408: Server is not ready yet

The device service should redirect the received URL to the correct application.

unregister

This method is used to unregister a push channel.

This shall be send to the notification server after a valid UA registration.

    
    {
      messageType: "unregister",
      channelID: "<a new channelID>"
    }
    
    

The server response can be:

      
      {
        messageType: "register",
        channelID: "<a new channelID>"
        status: 202
      }
      
      

      
      {
        messageType: "register",
        status: 4xx,
        reason: "<any reason>"
      }
      
      

on any error case, like:

• 408: Server is not ready yet

notification

This message will be used by the server to inform about new notification to the device.

All recieved notification(s) will have this structure:

    
    {
      messageType: "notification",
      updates: [
        {
          channelID: "<channelID>",
          version: "<versionNumber>"
        },
        {
          channelID: "<channelID>",
          version: "<versionNumber>"
        },
        ...
      ]
    }
    
    

On updates list, is returned all the list of pending notifications (last version of each channel)

desktop-notification

This message will be used by the server to inform about new desktop notification to the device.

These notifications SHOULD be showed into the device notification area.

All recieved notification(s) will have this structure:

    
    {
      messageType: "desktopNotification",
      updates: [
        {
          channelID: "<channelID>",
          _internal_id: "<id>",
          body: "<some text>"
        },
        {
          channelID: "<channelID>",
          _internal_id: "<id>",
          body: "<some text>"
        },
        ...
      ]
    }
    
    

On updates list, is returned all the list of pending notifications (last version of each channel)

ack

For each received notification through notification, the server SHOULD be notified in order to free resources related to this notifications.

This message is used to acknoledge the message reception.

      
      {
        messageType: "ack",
        updates: [
          {
            channelID: "<channelID>",
            version: "<versionNumber>"
          },
          {
            channelID: "<channelID>",
            version: "<versionNumber>"
          },
          ...
        ]
      }
      
      

Keep-alive algorithm

If it's needed a way to maintaint the socket open along time, a PING-PONG mechanism is also implemented.

The client sents an empty JSON object "{}" and the server will respond another empty object "{}" and/or a notification response (if pending notifications).

Wakeup websocket close

As explained before, when the client informs about the mobile network is in and the server has the required infrastructure in that mobile network, the websocket will be closed by the server after a predefined inactivity time (10 seconds).

When this timer fires, the websocket will be closed with the 4774 status code.

[WebSocket protocol] .

This chapter explains the different APIs available to third party servers

      
      kill -SIGUSR1 <pid>
      
    

      
      kill -SIGUSR2 <pid>
      
    

    
    version=<version_number>
    
    

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

This is a third party API which is independent of the PUSH protocol, so it's out of the scope of this document.

Anyway, through this API the publicURL received by the application should be send to his server.

Also this channel could be used to receive valid WATokens to be used during the WA registration.

The tokens are an important part of this API since it identifies each (user) actor (device and applications) in a unique or shared way.

When the handset is inside a mobile operator network, we can close the websocket to reduce battery comsuption and also network resources.

So, when the NS has messages to the WA installed on a concrete UA it will send a UDP Datagram to the handset.

When the mobile receives this datagram, it SHALL connect to the websocket interfaces in order to pull all pending messages.

The WakeUp server offers a simple HTTP API:

      
      kill -SIGUSR1 <pid>
      
    

      
      kill -SIGUSR2 <pid>