AeroGear provides a Java library that allows you to programmatically access and send notifications to the AeroGear Unified Push server. The library can be used in your standalone Java applications as well as be embedded in a Java EE environment. This guide will explain the features of the API as well as give example usages for both scenarios. We assume you are already familiar with the concepts of the AeroGear UnifiedPush server. If not, please visit the project’s github page for more information.

Installation

The library can be downloaded through the project github page or if you are using Maven, simply add the following dependency in your 'pom.xml':

API Overview

The API is straightforward to use and consists of the following methods:

public interface PushSender {
/**
* Sends the given payload to installations of the referenced PushApplication.
* We also pass a callback to handle the message.
*/
void send(UnifiedMessage unifiedMessage, MessageResponseCallback callback);
/**
* Sends the given payload to installations of the referenced PushApplication.
*/
void send(UnifiedMessage unifiedMessage);
...
}

The UnifiedMessage object passed as a parameter on those methods contain the actual notification payload. The object, as we will see in the example later on, utilizes the builder pattern to help you construct easily the payload. The difference between the two methods, is that the first one allows you to pass a callback so that you can be notified regarding whether the notification was successfully accepted by the server for transmission.

A concrete implementation of the PushSender interface can be found on the 'DefaultPushSender' class, which internally uses HttpURLConnection for the communication (but can easily be adopted to support other http providers).

In [1] we initialize the client passing the hostname of the running AeroGear UnifiedPush Server. If the hostname changes, you will need to create a new instance of the client. The pushApplicationId and masterSecret params are used to identify the particular Push Application on the UnifiedPush server as well as performing authentication against it. You were given them when you initially registered your PushApplication with the server. Ensure they are present and valid, otherwise there will be an error when trying to send.

In [2], we access the builder object and we use it to fill in the parameters.

Further, support is provided with the help of the userData param [3], to attach on the notification arbitrary key/value pairs that make sense on your business context. Those pairs will eventually be interpreted by your client code once the notification arrives.

An optional timeToLive [4] (in seconds) can be added on the notification payload configuration section, instructing the remote provider to drop the notification in case the device is unable to receive it (e.g. offline) for a period longer than the seconds specified.

Once the notification payload is constructed, we invoke the send method [5] passing along our callback. The’onComplete' callback will be called with the 'statusCode' initialized to the response code as returned from the server. Normally, a status code of '200' would be returned to indicate that the server accepted it for transmission. Check the server documentation for a list of valid responses.

Selected send

To narrow down the list of the recipients, you can use the the criteria builder. There are 2 ways of using this criteria builder :
- Start building your message by passing the criteria :

narrow down by specific aliases, thus allowing to send a message directly to a specific mobile installation. Note that here we used an email address, but anything that helps to identify a user can be used (e.g. username, user ID, etc)

.aliases(Arrays.asList("john@somewhere.com", "maria@somewhere.com"));

narrow down by specific device types:

.deviceType(Arrays.asList("iPhone", "iPad_Mini", "web"));

narrow down by specific categories:

.categories("someCategory", "otherCategory");

narrow down SimplePush clients:

.simplePush("version");

All these query criterias are optional. If no criterias are passed it will act as a broadcast send, where all clients are notified.

As you realize from the list, the Sender API offers tremendous flexibility in supporting even the most complex scenarios. You can mix and match options to target a specific mobile audience.

Once the UnifiedMessage is build with your desired criterias, simply call the send method on the JavaSender to send the notification.

Set the page in you application to launch when the user 'touches' the notification in the notification dock.
NOTE: For cordova applications set this to 'cordova' to launch your app and invoke the javascript callback.

.page("myPage")

Connect via a Proxy

If your infrastructure is behind a proxy, you can specify this while creating an instance of your SenderClient :

Integrating with Java EE

The library can be used inside a Java EE environment to enable your enterprise applications to send notification messages to mobile clients, when e.g. a particular business event occurs. Let’s see one approach of integration through an example of a PaymentGateway.

A payment request is initiated through a REST endpoint. The endpoint delegates the processing to an EJB and if the transaction succeeds, a CDI Payment Event is fired. The event is then picked up from CDI Observer bean, which then uses the JavaSender API to send a notification back to client.

Conclusion

The Sender API is simple and easy to use, allowing you to connect to the UnifiedPush server and send notifications. It can be used both in your standalone applications or be embedded in a Java EE environment. Work is being done to port it to other languages too and if you are interested you can give us a hand too! Please join our developer mailing list, or find us on IRC and introduce yourself!