SimplePushv1 Developers

Using the Push server as implemented on FirefoxOS 1.1 is really easy.

You, as a app developer, need to take care of the following things:

1. Add to your manifest file that you need push permission
2. Add a handler to your app when a new push notification arrives
3. Use correctly the navigator.push interface.
4. Sending notifications

Manifest

You need to add a push message and ask for push permissions as shown here:

  "messages": [
     { "push": "/index.html"},
     { "push-register": "/index.html"}
  ],
  "permissions": {
    "push": {}
  }

Message handler

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

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push', function(e) {
    debug('My endpoint is ' + e.pushEndpoint);
    debug('My new version is ' +  e.version);
    //Remember that you can handle here if you have more than
    //one pushEndpoint
    if (e.pushEndpoint === emailEndpoint) {
      emailHandler(e.version);
    } else if (e.pushEndpoint === imEndpoint) {
      imHandler(e.version);
    }
  });
} else {
  // No message handler
}

navigator.push interface

Register

if (navigator.push) {
  var req = navigator.push.register();
  
  req.onsuccess = function(e) {
    var endpoint = req.result;
      debug("New endpoint: " + endpoint );
    }

   req.onerror = function(e) {
     debug("Error getting a new endpoint: " + JSON.stringify(e));
   }
} else {
  // No push on the DOM
}

You can register() more than one channels (or endpoints) for your application. For example, one for each chat, or football match you are subscribed to.

Once you have your endpoint, you need to send it to your server, or to the service that will send notifications.

Unregister

var req = navigator.push.unregister(pushEndPoint)

req.onsuccess = function(e) {
  debug('PushEndpoint unregistered');
}

req.onerror = function(e) {
  debug('There was an error: ' + JSON.stringify(e));
}

Sending notifications

Once you have the endpoint on your server, to send a notification is as easy as send a HTTP PUT request to the endpoint with the body version=<version>. Imagine an endpoint with URL:

https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

and version 5:

version=5

With curl:

curl -X PUT -d "version=5" https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

If the server is running correctly, you will get a response with a 200 Status (OK) and a {} as a body. If not, a valid JSON explaining the error is sent.

Remember that version should be integer numbers, and incremental. Application will not get new notifications if the new version is lower than the stored on the server and/or device.

Use Telefonica's push notification server

You can override your build configured push server

1. adb shell stop b2g

2. adb shell ls /data/b2g/mozilla/ and write down the something.default directory, p.e: zw5oy38a.default

3. adb pull /data/b2g/mozilla/<your_id>.default/prefs.js

4. Edit the prefs.js file, changing the pref services.push.serverURL or adding the line user_pref("services.push.serverURL", "wss://ua.push.tefdigital.com");

5. adb push prefs.js /data/b2g/mozilla/<your_id>.default/prefs.js

6. adb shell start b2g

And the device will connect to the new push server. Any application that had endpoints for the old server will not work as device will not connect to the old push server.

Example

You can see a simple test app that uses push here: https://github.com/AntonioMA/tsimplepush/