Category Archives: tutorial

Having fun with Firefox OS and Chuck Norris


So, I was looking for a fun way to explain how to build Firefox OS Mobile Apps combined with AeroGear and I came across this awesome API : The Internet Chuck Norris Database API . This API returns you random Chuck Norris jokes and I thought that it could be cool to make a Mobile App that can receives , through notifications, these jokes. So, here we go !


What will learn in this post

                    • Building a Firefox OS Mobile Application
                    • Integrating Mozilla’s Simple Push service into your  app
                    • Using AeroGear, and more precisely
                    • Setting up and managing an UnifiedPush Server Instance to send Push Notifications, regardless from the underlying Push Network (although in this post we only cover Mozilla’s Simple Push Protocol, in the next post we will create the Android and the iOS version).
                    • Using AeroGear’s Pipes to consume REST Webservice.
                    • Using AeroGear’s Stores to persist locally your data.
                    • Integrating Mozilla’s Push Service with the UnifiedPush Server.

  What won’t be covered

                        • The backend logic : cURL will be used to send notifications. Another post will cover in details how to build your backend server.
                        • Angular : This app uses Angular but I won’t explain in details how Angular works. Don’t be scary if you have never touched it, it’s a pretty simple app and that could even give you a good overview on how Angular works.
                        • The Firefox OS recommended look and feel : Mozilla comes with a very nice documentation about the different layouts, widgets and colors that will make your app looks like an Firefox OS App. But since we plan, in the next posts, to port this app to other platforms (ios, Android), I decided to use Topcoat which is a really promising CSS Library with nice results on Mobile.


The complete application sources can be found here , feel free to fork & hack.

Setting up the UnifiedPush Server

The UnifiedPush Server is a project from the AeroGear team that will make the integration of Push Notifications into your Application as easy as Pie (the food, not the calculation). Basically, it’s divided in two parts : a server, handling the application registration and the sending of the notifications to the different Push networks (APNS, GCM, SPS) and a set of client libraries to register and consume these notifications. These libraries are available for the different supported platforms : iOS, Android and JavaScript. For our Firefox OS App we will be using the JavaScript library. The first thing we have to do is to set up an UnifiedPush Server, for that you have 3 options :

                      1. Clone the repository and build from the sources : mvn clean package
                      2. Grab a ready-to-use WAR file on bintray
                      3. Sign up for a Openshift Account (it’s free) and fire up a UnifiedPush Server Instance in the cloud in 2 clicks !

For option 1 and 2 you will need to run your server on a JBoss Server. If you’re are lazy and can’t wait to read these awesome Chuck Norris Jokes, for sure, go for option 3.

Basic Concepts

                      • Application : The Push Application, agnostic from any  platform, in our case we will have a “Chuck Push” Application
                      • Variant : A platform specific application belonging to the Push Application, in our case we will create a “Chuck Push Firefox OS” variant
                      • Installation : A device registered to one of the variants. This is handled by the client libraries.

The Admin Console

The UnifiedPush Server comes with a nice Admin UI Console that will make your life a lot easier. From there you can create your Push Applications and their related Variants. Let’s start by creating our “Chuck Push” Application :

                      • Browse to the admin console : http://localhost:8080/ag-push or , depending on what option you choose.
                      • Login, default credentials are admin / 123 and you will be prompted to change your password.
                      • On the right, press the “Create” Button and fill in the title and description :

Screen Shot 2014-02-11 at 23.11.21

                      • After the application has been created, you will be directed to the Application overview page. Choose the freshly created Application and on the next screen press “Add” in order to create a variant :

Screen Shot 2014-02-11 at 23.18.17

Be sure to select “SimplePush” as Network. So, we are done for now. We will come back later, to retrieve the generated IDs and passwords that will be needed by our App.

Application Structure

We have here a pretty standard structure, please be sure to grab a copy of aerogear.js here .


Some explanations on the most important files :

                  • manifest.webapp : The Firefox OS specific application description file.
                  • app.js will contain some initialisation code, including the registration to Mozilla’s Push Network and to our UnifiedPush server.
                  • dataService.js will contain the logic to consume the REST API and store the retrieved data locally.
                  • jokeController will handle the flow and manage the incoming notifications.
                  • jokes.html : A template that shows a joke.

The manifest.webapp : the entry point for your Firefox OS App

It’s time to start building the Mobile Application, let’s create a file named manifest.webapp that will “mark” our Application as a Firefox OS App and in the same time contain some important information :

  "version": "0.1",
  "name": "ChuckPush",
  "description": "ChuckPush Application for Firefox OS",
  "launch_path": "index.html",
  "developer": {
    "name": "AeroGear",
    "url": ""
"permissions": {
    "push": {},
    "desktop-notification": {}
  "messages": [
    { "push": "/" },
    { "push-register": "/" }

The important fields here are :

  • “launch_path” : Indicates which file starts the Application
  • “permissions” : Here we give permissions to the App to receive Push Notification, both in-app and on OS level.
  • “messages” : Indicates the path where the notification and the registration will occur.

Register to Mozilla’s Simple Push Network and the UnfiedPush Server

When the application starts we want to connect to Mozilla’s Push Network in order to receive messages but in the same time we want also to register with the UnifiedPush Server :

Let’s start by creating a configuration object :

var chuckConfig = {
  pushServerURL : "",
  variantID : "{your_variant_id}",
  variantSecret : "{your_variant_secret}"

Here, it’s time to go back to your UnifiedPush Admin console to grab the needed info : go to the variant you have created and you will see the values you need in the section “Authentication Info” . Also be sure to set the right URL pointing to your UnifiedPush Server.

Ok now let’s register our Client Application to Mozilla’s network :

var req = navigator.push.register();
  req.onsuccess = function() {
    jokeEndpoint = req.result;
    var jokeSettings = {
      metadata: {
        deviceToken: jokeEndpoint.substr(jokeEndpoint.lastIndexOf('/') + 1),
        simplePushEndpoint: jokeEndpoint



As you can see the important part is the navigator.push.register() This will handle under the hood  the registration to Mozilla’s Simple Push Network.

Then, we add a success function callback. In this function we will proceed to the registration to the UnifiedPush Server, for that we need some info retrieved from the first registration.

And finally :


will handle for us the registration of our device to the UnifiedPush Server.

So, we can now move on the other parts of the Application, let’s create two services : one to call the Chuck Norris REST API and one to store the results locally :

chuckPush.factory("dataService", function() {
	 return {
	   jokePipe : AeroGear.Pipeline({
       			name : "random",
       	settings : {
           		baseURL : "",
	    	jokeStore : AeroGear.DataManager({
			        name : "joke",
			        type : "IndexedDB",
			        settings : {
				            auto : true

We are doing 2 things here. First we define an AeroGear Pipe which can been seen as an abstraction around the classic jQuery Ajax call and secondly we create a AeroGear Store, of the type IndexedDB to persist our result, AeroGear’s Store are also a nice abstraction layer around the different local storage options present in the browser (LocalStorage, IndexedDB, WebSQL …).
Here we are just defining our service, let’s use them now in our controller :

function JokeController($scope, $location, $filter, dataService) {
    var jokePipe = dataService.jokePipe;
    var jokeStore = dataService.jokeStore;

    $scope.get = function() { {
	        $scope.results = data;

    navigator.mozSetMessageHandler('push', function(message) {{
    		        jsonp: true,
            		success : function(data) {
    				                success: function(){
                		var notification = navigator.mozNotification.createNotification("ChuckPush", data.value.joke);

Now, here is where the interesting things are happening. You will first note that we inject our dataService into the controller, that’s one of the nice features of Angular : Dependency Injection.

The first function $scope.get() is the one that will be called when the application starts. What it does is just reading the local store and putting the results in a variables that will be available for the view template. So, for showing data, we will always rely on the local store and that means that if even we are offline the application will still works !

Of course, the first time that your app will run, there will be no results since it hasn’t received any Notifications yet and that gives me a good transition to speak about the next big function we have in our controller that will handle the incoming notifications.

The function


is meant to set the function that will handle an incoming notification and what we do here is :

  • When a Notification arrives call our Pipe to get a random joke (which will result in a GET Also, notice how easy it is to add jsonp support just by setting the option to true.
  • If the Pipe call is a success then we store that in our local store
  • Finally, we create a Notification object, containing the joke and be calling show() a nice Notification UI Widget will be fired, even if the app is running in background.

Ok, the last part is to make a view template that will display our jokes :

<div class="topcoat-list__container">
<h3 class="topcoat-list__header">Jokes</h3>
		<ul class="topcoat-list list">
			<li ng-repeat="result in results" class="topcoat-list__item">
   		 	 <span class="chevron"></span>

And to be complete, here is our main page :

<html lang="en" ng-app="chuckPush">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css"
<script src=''></script>
<script src=""></script>
<script src=""></script>

<script src="js/aerogear.js"></script>
<script src="js/app.js"></script>
<script src="js/service/dataService.js"></script>
<script src="js/services/notifierService.js"></script>
<script src="js/controller/jokeController.js"></script>

	<div class="topcoat-navigation-bar">
		<h1 class="topcoat-navigation-bar__title">ChuckPush</h1>
	<div ng-view>


I remind you that the whole source code can be find here since it took some shortcuts in the blog to make the stuff more readable.

Testing our application

We are done and ready to deploy our application, for that you have 2 options :

  1. Deploy on your Firefox OS device
  2. Deploy on the Firefox OS Simulator

Whatever you choose, you will need the Firefox OS Simulator because it’s also used to push your apps to the devices. The simulator is a Firefox add-on that be found here , once installed you can start it through the menu :   Tools > Web Developper > Firefox OS simulator.

Then you just have to push “Add Directory” and point to your manifest.webapp file. If you device is connected you should have a button “push” under your app listed on the dashboard. But it’s always good to first try it out on the simulator, you can do that just be hitting the “Refresh” button. That will start the simulator in a new window.

It’s also good to have some debug and network information, press the “connect” button and Firefox’s Developer tools will connect with your simulator !

Sending Push Notifications

So, our app is running but it’s not showing any jokes. That’s normal since we did not sent any notifications yet, so let’s do that.

Normally, sending notifications is the responsibility of a backend Application but since this isn’t really in the scope of the post we will skip that and send directly messages to the UnifiedPush Server which will then dispatch the message to the Mozilla’s Push Network.

So let’s use cURL but before that go back to your UnifiedPush Admin Console to grab the the Push Application Id and the Master Secret, these can be found under the “Authentication Info” section of your Application (be careful not the variant but the “parent” application) :

curl -3 -u "{your_push_app_id}:{your_master_secret}" -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{
           "simple-push": "version=123"

Be sure to change the values, including the URL of the UnifiedPush Server. As you can see the message format is very simple, not really surprising since we are (for now) only sending on Mozilla’s Simple Push network. The Simple Push Protocol must be seen as a “door bell” to wake-up/make react the mobile app, it does not have any payload. It has just a version, that must be unique, so if your are sending a second notification make sure to change the value of it (i.e version=666)

Ok, send the cURL command, wait a bit and you should see (and hear !) a notication popping up on the simulator (or your device) ! We are done, you can now take some time to laugh about the joke you just received.

In the next posts, we will see how to deal with iOS and Android platforms that can handle Notifications containing an actual payload, we will also see how to build the backend for our app and add some cool features to it.


 Resources :