A JBoss Project
Red Hat

AeroGear Cordova Push Plugin

The AeroGear Cordova Push Plugin is an extension of the standard Cordova Push Plugin the difference is that it’s that it supports AeroGears UnifiedPush better and that makes that there is less boiler plate to take care of in your javascript.

Before we start please install Apache Cordova CLI, which is the command line tool to build, deploy and manage Cordova-based applications.

Make sure you have the 3rd party configuration, required by GCM or APNs:

Getting Started

The Cordova command line tooling is based on node.js so first you’ll need to install node then you can install Cordova by executing:

$ npm install -g cordova

To deploy on iOS you need to install the ios-deploy package as well

$ npm install -g ios-deploy

Create the App

Create a new app by executing:

$ cordova create <project-name> [app-id] [app-name]

Add platform(s)

Specify a set of target platforms by executing:

$ cordova platform add <platform>

The available platform values are ios and android.

Install the plugin

Install the aerogear-pushplugin-cordova plugin by executing:

$ cordova plugin add org.jboss.aerogear.cordova.push

or if you want the latest and greatest development version you can install the version from the git repo like so:

$ cordova plugin add https://github.com/aerogear/aerogear-pushplugin-cordova.git

Done! Your project now contains the AeroGear PushPlugin. For an integration with the UnifiedPush Server open the www folder in your text editor and apply the code from the example below. Afterwards you can execute the project with cordova run <platform>.

Sample Example

There are two ways to register a device in the AeroGear UnifiedPush Server devices registry :

  • Passing the config parameters directly in the JavaScript code :

var pushConfig = {
    pushServerURL: "<pushServerURL e.g http(s)//host:port/context >",
    alias: "<alias e.g. a username or an email address optional>",
    android: {
      senderID: "<senderID e.g Google Project ID only for android>",
      variantID: "<variantID e.g. 1234456-234320>",
      variantSecret: "<variantSecret e.g. 1234456-234320>"
    },
    ios: {
      variantID: "<variantID e.g. 1234456-234320>",
      variantSecret: "<variantSecret e.g. 1234456-234320>"
    }
};

push.register(onNotification, successHandler, errorHandler, pushConfig);
  • Using an external configuration file named push-config.json, placed inside the www folder :

{
   "pushServerURL": "<pushServerURL e.g http(s)//host:port/context >",
   "android": {
      "senderID": "<senderID e.g Google Project ID only for android>",
      "variantID": "<variantID e.g. 1234456-234320>",
      "variantSecret": "<variantSecret e.g. 1234456-234320>"
   },
   "ios": {
      "variantID": "<variantID e.g. 1234456-234320>",
      "variantSecret": "<variantSecret e.g. 1234456-234320>"
   }
}

And then in your JavaScript :

push.register(onNotification, successHandler, errorHandler);

The onNotification callback will get executed by the plugin when a new message arrives. If you are only targeting one platform you can simplfy the config (or your push-config.json file) above like:

var pushConfig = {
    pushServerURL: "<pushServerURL e.g http(s)//host:port/context >",
    alias: "<alias e.g. a username or an email address optional>",
    variantID: "<ios variantID e.g. 1234456-234320>",
    variantSecret: "<ios variantSecret e.g. 1234456-234320>"
};

push.register(onNotification, successHandler, errorHandler, pushConfig);

Start receiving messages:

function onNotification(event) {
    alert(event.alert);
}

The passed in event object contains:

  • alert the alert message send

  • coldstart was the app running when the message was received

  • badge the number to display on the icon ios specific

  • any custom set properties are available under e.payload ( e.g alert(e.payload.foo); )

Also have a look here for more information about the message sending and properties

iOS background notification

Sending notifications that contain content-availble on iOS will call the javacript first before launching the app, this will enable you to update the UI or do a silent push (e.g. without an alert) to update the content of your app without the user noticing. After fetching the content you’ll have to inform the os about the result by calling setContentAvailable with either NewData, NoData or Failed AeroGear Push plugin API

function onNotification(event) {

  if (event['content-available'] === 1) {
    if (!event.foreground) {
      // fetch content
      push.setContentAvailable(push.FetchResult.NewData);
    }
  }
}

To unregister (only available on Android):

push.unregister(successHandler, errorHandler);

function successHandler() {
    console.log('success')
}

function errorHandler(message) {
    console.log('error ' + message);
}

Full example (index.html):

<!DOCTYPE HTML>
<html>
<head>
  <title>Demo</title>
</head>
<body>

<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8" src="jquery_1.5.2.min.js"></script>

<script type="text/javascript">

  function onDeviceReady() {
    var pushConfig = {
        pushServerURL: "<pushServerURL e.g http(s)//host:port/context >",
        alias: "<alias e.g. a username or an email address optional>",
        android: {
          senderID: "<senderID e.g Google Project ID only for android>",
          variantID: "<variantID e.g. 1234456-234320>",
          variantSecret: "<variantSecret e.g. 1234456-234320>"
        },
        ios: {
          variantID: "<variantID e.g. 1234456-234320>",
          variantSecret: "<variantSecret e.g. 1234456-234320>"
        }
    }

    var statusList = $("#app-status-ul");
    statusList.append('<li>deviceready event received</li>');

    try {
      statusList.append('<li>registering </li>');
      push.register(onNotification, successHandler, errorHandler, pushConfig);
    } catch (err) {
      txt = "There was an error on this page.\n\n";
      txt += "Error description: " + err.message + "\n\n";
      alert(txt);
    }
  }

  function onNotification(e) {
    var statusList = $("#app-status-ul");

    // if the notification contains a sound, play it.
    if (e.sound && (typeof Media != 'undefined')) {
      //install the media plugin to use this
      var media = new Media("/android_asset/www/" + e.sound);
      media.play();
    }

    if (e.coldstart) {
      statusList.append('<li>--COLDSTART NOTIFICATION--' + '</li>');
    }

    statusList.append('<li>MESSAGE -> MSG: ' + e.alert + '</li>');

    //only on ios
    if (e.badge) {
      push.setApplicationIconBadgeNumber(successHandler, e.badge);
    }
  }

  function successHandler() {
    $("#app-status-ul").append('<li>success</li>');
  }

  function errorHandler(error) {
    $("#app-status-ul").append('<li>error:' + error + '</li>');
  }

  document.addEventListener('deviceready', onDeviceReady, true);

</script>
<div id="home">
  <div id="app-status-div">
    <ul id="app-status-ul">
      <li>AeroGear PushPlugin UnifiedPush Demo</li>
    </ul>
  </div>
</div>
</body>
</html>