A JBoss Project
Red Hat

Aerogear Guides Tutorials to help get you off and running.

UnifiedPush Server User Guide

Overview

The AeroGear UnifiedPush Server is a server that allows sending native push messages to different mobile operating systems. Currently the server supports

About the UnifiedPush Server

The AeroGear UnifiedPush Server offers a unified Notification Service API to the above mentioned Push Network Services. When a push message request is sent to the UnifiedPush Server, it is internally translated into the format of these 3rd party networks. This gives a server the ability to send Push notifications to different mobile platforms.

When using the UnifiedPush Server, please keep in mind that Push notification is a signalling mechanism and that it is not suitable to be used as a data carrying system (e.g. use in a chat application).

Privacy note

As explained in the How the UnifiedPush Server works section, the payload of the push notification is delivered to 3rd party Push Network providers, like Google or Apple.

It is highly recommended to not sent any send sensitive personal or confidential information belonging to an individual (e.g. a social security number, financial account or transactional information, or any information where the individual may have a reasonable expectation of secure transmission) as part of any Push Notification!

For analytic purposes on our Dashboard we store the content of the alert key sent to the UnifiedPush Server. The content of the alert key belongs to the metadata, which is deleted after 30 days, using a nightly job within the UnifiedPush Server.

Use-cases and scenarios

Different use-cases and scenarios are supported. Below are a few to give an idea how the UnifiedPush Server can be used:

  • MyWarehouseInc-backend can send notification messages to different groups (e.g. discounts for only iOS (or only Android) users)

  • MyInsuranceCorp-backend can send “notification messages” to different variants of its mobile Applications:

    • App for the Customers

    • App for the employed Sales Agents

  • Publishing Company:

    • MyPublishing-Company-backend sends update “notification messages” to all of its apps (free and premium - regardless of the mobile OS)

    • Targeting: Sending push messages to different groups of users. For instance, availability of “advanced content” is only notified to the paying customers (e.g. those that run the premium app).

  • A company has different backends (small/simple apps for different tasks) - and these different backends could be able to reach all (or some) of the company’s mobile apps.

Motivation: Easy use of Push Notifications for any (JBoss/AeroGear powered) mobile application, that is backed by JBoss technology (e.g. LiveOak, Drools, etc.).

Useful Terminology

Before we get into details, it’s important that we have a good lexicon.

PushApplication

A logical construct that represents an overall mobile application (e.g. Mobile HR).

Variant

A variant of the PushApplication, representing a specific mobile platform, like iOS or Android, or even more fine grain differentiation like iPad or iPhone. There can be multiple variants for a single PushApplication (e.g. HR Android, HR iPad, HR iPhone free or HR iPhone premium). Each supported variant type contains some platform specific properties, such as a Google API key (Android) or passphrase and certificate (Apple).

Installation

Represents an actual device, registered with the UnifiedPush Server. User1 running HR Android app, while User2 runs HR iPhone premium on his phone.

Push Notification Message

A simple message to be sent to a PushApplication.

Sender Endpoint API

A RESTful API that receives Push Notification Message requests for a PushApplication or some of its different Variants. The Server translate this request into the platform specific details and delivers the payload to the 3rd party cloud provides, which eventually might deliver the message to the physical device.

How the UnifiedPush Server Works

The AeroGear UnifiedPush Server can be seen as a broker that distributes push messages to different 3rd party Push Networks. The graphic below gives a little overview:

How it works

  1. One PushApplication and at least one mobile platform variant must be created (see Using the Admin UI).

  2. The variant credentials that are generated and stored by the UnifiedPush Server must be added to the mobile application source, enabling the application running on the mobile device to register with the UnifiedPush Server once it is installed on mobile devices (see tutorials).

  3. Sending a push message can happen in different ways: The AdminUI can be used to send a (test) message to registered devices, as explained in Sending a Push Notification. However, in a real-world scenario the Push Notification Message request is triggered from a backend application, which sends its requests using the Sender API. Different SDKs for different languages are supported (see Sending a Push Notification from Code).

  4. The push request is then translated into platform specific details for the required variant Push Network. The Dashboard of the AdminUI gives a status report if a message is sent to the Push Network, as described in Dashboard.

  5. The UnifiedPush Server does not directly deliver the message to the mobile device. This is done by the appropriate variant Push Network. Note: There can be latency in the actual delivery. Most Push Networks, such as APNs or GCM, do not guarantee to deliver messages to mobile devices.

Now that you are familiar with the basics of the UnifiedPush Server it is time for the Installation and configuration part!

Install and Configure the UnifiedPush Server

Getting the UnifiedPush Server up and running with an on-premise application server is a four-step setup process:

Each of these steps is detailed here, with instructions and useful scripts provided for the supported databases (MySQL, PostgreSQL) and application servers (EAP 6.4.0 GA, WildFly 8.x). Make sure to run them in the full-profile mode as discussed below!

You can also run the UnifiedPush Server in the cloud with OpenShift but this requires a different setup process.

Get the UnifiedPush Server Application Files

The UnifiedPush Server application is provided in two files: unifiedpush-server.war and unifiedpush-auth-server.war. These files contain the core functionality and authentication components of the UnifiedPush Server. Both files are necessary to achieve a working UnifiedPush Server application.

Download the latest copies of these files using the following link:

Different files are provided for each application servers:

  • For WildFly, unifiedpush-server-wildfly.war

  • For EAP, unifiedpush-server-as7.war

Configure JMS destinations for the UnifiedPush

The UnifiedPush Server 1.2.x requires JMS queues and topics that it uses for token loading, notification dispatching and metrics collection.

Following CLI script creates all required JMS destinations and also configures address settings that influence JMS destinations behavior:

$ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/jms-setup-wildfly.cli

Generate the UnifiedPush Database and Datasource

The UnifiedPush Server requires an accompanying database in which to store push application, variant and installation details. You can use the database of your choice but the corresponding datasource added to the application server must have JNDI name java:jboss/datasources/UnifiedPushDS.

Information is provided here for generating UnifiedPush datasources for several database types. Note that if the intended application server has not previously been used with the chosen database type, additional configuration must also be completed in order to enable the application server to connect to the database. As detailed here, sources and scripts are available to assist with all these processes.

MySQL Database

You can use a MySQL database with the UnifiedPush Server. As demonstrated here, the application server must first be configured for MySQL and the UnifiedPush MySQL database must exist before the application server can be configured with the associated UnifiedPush datasource.

To complete these prerequisite processes and configure the application server for the UnifiedPush MySQL database, complete the following steps:

  1. Copy the MySQL module, located in the databases/src/main/resources/modules/com directory of the release bundle, to the application server modules directory

    $ cp -r /path/to/com /path/to/SERVER_HOME/modules/
  2. Add the MySQL JDBC driver to the application server mysql module

    $ mvn dependency:copy -Dartifact=mysql:mysql-connector-java:5.1.18 \
    -DoutputDirectory=/path/to/SERVER_HOME/modules/com/mysql/jdbc/main/
  3. Create the UnifiedPush MySQL database

    For 1.0.x :

    $ mysql -u <user-name>
    mysql> create database unifiedpush default character set = "UTF8" default collate = "utf8_general_ci";
    mysql> create user 'unifiedpush'@'localhost' identified by 'unifiedpush';
    mysql> GRANT SELECT,INSERT,UPDATE,ALTER,DELETE,CREATE,DROP ON unifiedpush.* TO 'unifiedpush'@'localhost';

    For 1.1.x :

    $ mysql -u <user-name>
    mysql> create database unifiedpush default character set = "UTF8" default collate = "utf8_general_ci";
    mysql> create database keycloak default character set = "UTF8" default collate = "utf8_general_ci";
    mysql> create user 'unifiedpush'@'localhost' identified by 'unifiedpush';
    mysql> GRANT SELECT,INSERT,UPDATE,ALTER,DELETE,CREATE,DROP,INDEX ON unifiedpush.* TO 'unifiedpush'@'localhost';
    mysql> GRANT SELECT,INSERT,UPDATE,ALTER,DELETE,CREATE,DROP ON keycloak.* TO 'unifiedpush'@'localhost';
  4. Start the application server, using the full-profile mode

    $ ./path/to/SERVER_HOME/bin/standalone.sh --server-config=standalone-full.xml
  5. Configure the application server to use the MySQL driver and create and add the UnifiedPush datasource for the MySQL database using the application server CLI and downloaded configuration script, located in the databases directory of the release bundle

    For WildFly:

    $ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/mysql-database-config-wildfly.cli

    For EAP:

    $ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/mysql-database-config.cli

PostgreSQL Database

You can use a PostgreSQL database with the UnifiedPush Server. As demonstrated here, the application server must first be configured for PostgreSQL and the UnifiedPush PostgreSQL database must exist before the application server can be configured with the associated UnifiedPush datasource.

To complete these prerequisite processes and configure the application server for the UnifiedPush PostgreSQL database, complete the following steps:

  1. Copy the PostgreSQL module, located in the databases/src/main/resources/modules/org directory of the release bundle, to the application server modules directory

    $ cp -r /path/to/org /path/to/SERVER_HOME/modules/
  2. Add the PostgreSQL JDBC driver to the application server postgresql module

    $ mvn dependency:copy -Dartifact=org.postgresql:postgresql:9.2-1004-jdbc41 \
    -DoutputDirectory=/Path/to/SERVER_HOME/modules/org/postgresql/main/
  3. Create the UnifiedPush PostgreSQL database

    For 1.0.x :

    $ psql -U <user-name>
    psql> create database unifiedpush;
    psql> create user unifiedpush with password 'unifiedpush';
    psql> GRANT ALL PRIVILEGES ON DATABASE unifiedpush to unifiedpush;

    For 1.1.x :

    $ psql -U <user-name>
    psql> create database unifiedpush;
    psql> create database keycloak;
    psql> create user unifiedpush with password 'unifiedpush';
    psql> GRANT ALL PRIVILEGES ON DATABASE unifiedpush to unifiedpush;
    psql> GRANT ALL PRIVILEGES ON DATABASE keycloak to unifiedpush;
  4. If necessary, enable UnifiedPush Server access to the PostgreSQL database by adding the following lines to your $POSTGRES_HOME/data/pg_hba.conf file

    host    all             unifiedpush     127.0.0.1/32            md5
  5. Start the application server, using the full-profile mode

    $ ./path/to/SERVER_HOME/bin/standalone.sh --server-config=standalone-full.xml
  6. Configure the application server to use the PostgreSQL driver and create and add the UnifiedPush datasource for the PostgreSQL database using the application server CLI and downloaded configuration script, located in the databases directory of the release bundle

    For WildFly:

    $ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/postgresql-database-config-wildfly.cli

    For EAP:

    $ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/postgresql-database-config.cli

Create the database schema

After the application server is configured for the UnifiedPush datasource, the schema must be created. Inside of the release bundle there is a migrator folder which contains a command line interface to create the required database schema. The tool is also used to migrate from an existing schema to a newer version of the schema, used for the UnifiedPush Server.

Copy the liquibase example file to liquibase.properties and edit it to match your database name and credentials.

cp liquibase-database-flavor-example.properties liquibase.properties

After the liquibase.properties contains the proper credentials, you need to execute the migration tool:

./bin/ups-migrator update

In case of a successful run, the script prints

Liquibase Update Successful

Deploy the UnifiedPush Server

With the database schema in place, the two UnifiedPush Server application .war files must both be deployed to the application server to achieve a complete and operational UnifiedPush Server.

To deploy the UnifiedPush Server, copy the two .war files to /path/to/SERVER_HOME/standalone/deployments/. This can be done either before or after starting the application server.

After deployment with the application server running, the UnifiedPush Server Console can be accessed at http://localhost:8080/ag-push/. For information about using the Console, see Using the Admin UI.

Database Migration

For migrating the database schema to a new version the migration tool from the above Create the database schema section is used. For details around the database migration, consult the Migration guide.

UPS Configuration Properties

For an advanced configuration (or just plain testing purposes), it is possible to launch the UPS with a bunch of different properties - some of them can be configured via System Properties, others can be configured as a configuration of JMS subsystem and other are configured of EJB.

System Properties for the UnifiedPush Server

Name Description Default Value

custom.aerogear.apns.push.host

Defines a custom URL for APNs push server

no value, defaulting to Apple’s service

custom.aerogear.apns.push.port

Defines a custom port for APNs push server

no value, defaulting to Apple’s service

custom.aerogear.apns.feedback.host

Defines a custom URL for APNs feedback server

no value, defaulting to Apple’s service

custom.aerogear.apns.feedback.port

Defines a custom port for APNs feedback server

no value, defaulting to Apple’s service

aerogear.android.batchSize

Specifies how many Android devices tokens will be loaded and delivered in one batch

1000

aerogear.android.batchesToLoad

Specifies how many Android batches should be loaded in one token-loading transaction.

10

aerogear.ios.batchSize

Specifies how many iOS devices tokens will be loaded and delivered in one batch

10000

aerogear.ios.batchesToLoad

Specifies how many iOS batches should be loaded in one token-loading transaction.

3

aerogear.simplePush.batchSize

Specifies how many SimplePush client tokens will be loaded and delivered in one batch

1000

aerogear.simplePush.batchesToLoad

Specifies how many SimplePush batches should be loaded in one token-loading transaction.

10

aerogear.windows_wns.batchSize

Specifies how many Windows-8 tokens will be loaded and delivered in one batch

1000

aerogear.windows_wns.batchesToLoad

Specifies how many Windows-8 batches should be loaded in one token-loading transaction.

10

aerogear.windows_mpns.batchSize

Specifies how many Windows-10 devices tokens will be loaded and delivered in one batch

1000

aerogear.windows_mpns.batchesToLoad

Specifies how many Windows-10 batches should be loaded in one token-loading transaction.

10

aerogear.adm.batchSize

Specifies how many Amazon devices tokens will be loaded and delivered in one batch

1000

aerogear.adm.batchesToLoad

Specifies how many Amazon batches should be loaded in one token-loading transaction.

10

Configuring System Properties via CLI configuration arguments

It is possible to specify one or more of the above system properties, when launching the Java EE container, like:

$ ./path/to/SERVER_HOME/bin/standalone.sh -Daerogear.ios.batchSize=2000

Configuring System Properties via XML configuration file

It is also possible to include the desired system variables into the standalone-full.xml configuration file:

...
</extensions>

<system-properties>
   <property name="aerogear.ios.batchSize" value="2000"/>
   ...
</system-properties>

Configuring JMS messaging subsystem

By default, JMS queues and topics required for UnifiedPush Server to work are installed via CLI script jms-setup-wildfly.cli.

The properties of these queues and topics can be configured to change characteristics of message delivery.

Some queues are configured for each supported Push Network: Adm, APNs, GCM, MPNS, SimplePush, WNS. In the table it is represented as a placeholder {Network}.
JMS Destination Properties Explanation

/queue/{Network}PushMessageQueue

redelivery-delay=1500

when TokenLoader fails to load tokens (for example when the queue it pushes tokens to is full) it will retry delivery in 1.5s

/queue/{Network}PushMessageQueue

redelivery-multiplier=1.5, max-redelivery-delay=5000

redelivery-delay is increased after repeated failure until it reaches 5s

/queue/{Network}TokenBatchQueue

address-full-policy=FAIL

when the token queue is full, the TokenLoader will fail, and it will be redelivered according to properties of {Network}PushMessageQueue

/queue/{Network}TokenBatchQueue

max-size-bytes=40000

specifies how many tokens can be stored for given {Network} (in bytes)

/queue/TriggerMetricCollectionQueue

redelivery-delay=1000

trigger MetricCollector every 1 second until all metrics are collected

The properties can be configured either during installation by modifying the installation CLI script or once installed, they can be changed in <address-settings> section of standalone-full.xml.

Configuring workers

UnifiedPush Server uses Message-Driven Beans (MDBs) as workers for processing internal JMS events.

The number of created workers can be configured by tweaking activation config property maxSession in /WEB-INF/jboss-ejb3.xml configuration file in the deployed WAR.

By default, there are 15 workers for processing each of the queues.

The only exception is /queue/APNsTokenBatchQueue which has limit of 10 workers, which is given by the limit of maximum 10 connections to APNs per one certificate.
In order to fully understand how JMS Internals work in UnifiedPush Server, see Appendix section.

Cluster configuration

The previous section describes the installation via a single standalone instance, while here some more advanced topics such as WildFly clustering or Docker are discussed.

Cluster in WildFly Standalone HA

For the standalone configuration option of WildFly it is also possible to enable clustering, using the different ha configuration options:

  • standalone-ha.xml

  • standalone-full-ha.xml

Since the UnifiedPush Server requires a full profile, we need to start the server using the the standalone-full-ha.xml file:

$ ./path/to/NODE_x/bin/standalone.sh --server-config=standalone-full-ha.xml -Djboss.node.name=NameOfTheNode -Djboss.messaging.cluster.password=SomePassword -Djava.net.preferIPv4Stack=true

Each node needs to get a unique name inside of the cluster, that is another slight difference to running a single standalone instance.

In case the different nodes are running on the same machine, it is required to also apply the jboss.socket.binding.port-offset configuration, e.g -Djboss.socket.binding.port-offset=100, for a different port on the other nodes.

All other steps are exactly the same, including setting up the Database as well and the Deployment of the UPS WAR files.

For deployments on nodes, running on a different port, make sure to specify the port via jboss-cli or the WildFly Maven Plugin.

On OS X, you need to enable multicast first:

sudo route add -net 224.0.0.0/5 127.0.0.1

Cluster in WildFly Domain Mode

Another option to run a WildFly cluster running it as a Managed Domain, which allows you to run and manage a multi-server domain topologyis in a more centralized way, as discussed in the WildFly documentation.

Arun Gupta did a short screencast on how to configure a Managed Domain.

Once the Managed WildFly server is configured and running, like in the standalone server it is time to setup the Database and JNDI datasource. Since the process is pretty much the same, this section focuses on MySQL as the canonical database:

  1. Copy the MySQL module, located in the databases/src/main/resources/modules/com directory of the release bundle, to the application server modules directory

    $ cp -r /path/to/com /path/to/SERVER_HOME/modules/
  2. Add the MySQL JDBC driver to the application server mysql module

    $ mvn dependency:copy -Dartifact=mysql:mysql-connector-java:5.1.18 \
    -DoutputDirectory=/path/to/SERVER_HOME/modules/com/mysql/jdbc/main/
  3. Database setup

    Like described in the previous section, you can install the MySQL server on your machine and setup the required schema, or you can use a Docker-based MySQL server, as explained here.

  4. Configure the application server to use the MySQL driver and create and add the required UnifiedPushDS and KeycloakDS datasource for the MySQL database using the application server CLI and downloaded configuration script, located in the databases directory of the release bundle:

    $ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/mysql-database-config-wildfly-managed-domain.cli
  5. Deploy the UnifiedPush Server

    To deploy the UnifiedPush Server, you need to invoke another command line script. The script ensures the deployment is propagated down to all nodes of the Managed Domain:

    $ ./path/to/SERVER_HOME/bin/jboss-cli.sh --file=/path/to/mysql-database-config-wildfly-managed-domain.cli

    After deployment with the application server running, the UnifiedPush Server Console can be accessed at http://localhost:8080/ag-push/. For information about using the Console, see Using the Admin UI.

Docker

You need to have Docker and Docker Compose installed to follow the instructions. For Windows or Mac OS X the installation of Docker is quite different, using boot2docker.

UnifiedPush Server as a Docker container

The simplest version to run the Push Server is via Docker. The AeroGear team has a docker image on Docker Hub, that is easy to run:

docker run -it -p YOUR_PORT:8443 aerogear/unifiedpush-wildfly

Afterwards the server is TLS enabled and you can access it via https://DOCKER_IP:YOUR_PORT/ag-push

Databases via Docker

In case you just want to virtualize the databases, that’s possible too. For the UnifiedPush Server we need two datasources: * one for the Push server data * one for the Keycloak server

The easiest way to run multiple Docker containers is using Docker Compose. In the docker folder of the download bundle, there is a ups-datasource.yml file, which is used by the following comannd:

$ docker-compose up -d

Once the command is done, you have two MySQL servers, running on the specified ports.

With docker ps you can see the running processes on the commandline!

Running the UnifiedPush Server on OpenShift

AeroGear provides an UnifiedPush Server cartridge to make it easy to get it running on OpenShift. If you don’t already have an account or don’t know how to create applications go to https://www.openshift.com/ first. You can create the UnifiedPush Server instance either with the web tool or the command line tool, both approaches are described below.

It’s important that immediately after creating an UnifiedPush Server instance you open the AdminUI and login to reset the password. If this is not done anyone can easily gain admin rights to your UnifiedPush Server instance.

Create an instance using OpenShift’s Web UI

The easiest way to run on OpenShift is to the click the button below:

Run me on Openshift

Now, just fill in the form and click on Create Application! This creates an UnifiedPush Server instance with a configured MySQL 5.5 database. Click on Continue to the application overview page. Under the list of applications you should find your new UnifiedPush Server instance and the status should be Started. Click on it to open the UnifiedPush Server’s homepage.

Create an instance using OpenShift’s command line interface

Make sure the OpenShift Client tools are correctly installed and run the following command from a terminal:

rhc app create --no-git <APPLICATION NAME> https://cartreflect-claytondev.rhcloud.com/reflect?github=aerogear/openshift-origin-cartridge-aerogear-push

Replace <APPLICATION NAME> with the name you want (for example unifiedpush).

Once the instance is created the rhc tool outputs details about it. Open the returned URL in a browser to open the UnifiedPush Server’s homepage.

Documentation on rhc

If you are interested to learn more about rhc, checkout the following resources:

Next Steps

Now it is time to make yourself familiar with the Admin UI.

Using the Admin UI

The Unified Push Server can be accessed via its RESTful endpoints, as well over an administrative user interface.

Admin and Developer accounts

Once installed, the Unified Push Server comes with two different account types:

  • a single admin user

  • a developer role

The difference between the admin and developer account types is that the former can access all PushApplications and Variants configured on the server, whereas the latter has access only to the PushApplications and Variants created by the actual user. Further, the administration of the Unified Push Server, as well as management of it’s users in the Keycloak Admin Console, can only be performed by the admin.

By default there is no developer account and one needs to be explicitly created by the admin inside of the Keycloak Admin Console!

Login and landing page

Once you have the Unified Push Server running, whether on Openshift or standalone, it is time to open the AdminUI, by accessing http(s)://SERVER:PORT/ag-push in your browser. You are prompted by a login dialog:

Login to the Unified Push Server

The default credentials for the admin are admin/123.

On the very first login you are asked to update the password. It is a wise idea to change it to something completely different.

After applying the password you are able to use the AdminUI of the Unified Push Server:

List of PushApplications

Right after a fresh installation you won’t have any PushApplication in our database. In this case you will see the Wizard (learn more in Wizard section) as the landing page.

Account Management

To manage some details on your account, you need to click on the username (admin in this case) in the right hand corner of the screen. This opens a context menu where you click on Account Management:

Go to the Account Management page

This brings you to the page where you can configure details about your account. The first option allows you to provide additional information like your name and your email address:

Account Details

The next section allows you to update your current password.

Please make sure to pick a strong password, see the admin user as the root on your machine…​

Password Details

It is also possible to use the Google Authenticator app as an additional security mechanism for your login:

Setup an authenticator

On the Sessions menu there is an overview of all client sessions that are currently active. If the session is connected via a browser the only information that is presented in the table below is the IP address of the client:

List of OAuth client sessions

On the Applications menu you see a read-only list of all application clients that have rights to access the Unified Push Server:

List of OAuth client sessions

To go back to the Unified Push AdminUI click the marked link on the right corner, this performs a redirect to the previous landing page:

Going back to the Unified Push AdminUI

The Wizard

To be able to use the Unified Push Server for your mobile development you need to create a PushApplication and at least one Variant. The PushApplication is a logical construct, that represents an overall mobile application container for its different mobile platforms, which are called Variants. The Wizard is used to create a PushApplication and one Variant. The Wizard is launched when clicking the Create Application button on the overview page:

Create Application

Wizard: Start!

Before diving into the details the Wizard shows an overview page, containing a bit more details on the steps inside the wizard:

Wizard - overview

Wizard: Step 1

To create a new PushApplication click the START HERE button, which brings you to the first step of the Wizard, asking for the name of your PushApplication:

Wizard - PushApplication

At any time, you can skip the workflow of the Wizard, by clicking the Skip the wizard link on the top right!

Wizard: Step 2

Since the PushApplication is a container for different platforms you need to create a Variant for a specific mobile platform, like Android, iOS or Windows.

Wizard - Add Variant

Next click on the +Add A Variant button in the screen above, which brings you to the details page for the Variant:

Wizard - Variant details

In this example we are creating an Android Variant and giving it a name. Besides the name, each supported variant type contains some platform specific properties, such as a Google Cloud Messaging key (Android) or passphrase and certificate (Apple). In this case we enter the require GCM Key and the GCM Project Number.

If you are not familiar with the details of your desired mobile platform, click here for Android, here for Apache Cordova, here for iOS and here for Windows.

After finishing the above dialog you are coming to the details page of the newly created Variant:

Wizard - code snippets

The page contains some code snippets that are specific to the underlying mobile platform (e.g. Android), which allows your mobile application, running on a device, to register itself against the Unified Push Server for push notification delivery.

In our Android example you are getting two options:

  • Native Android source code

  • JavaScript for Apache Cordova

Wizard: Step 3

The next step in the Wizard gives the option to send a test push notification to the devices that are registered with the Variant. In this case we have registered devices and can use the textfield to send a test notification:

Wizard - Test notification

However, the textfield will be disabled in case there are no devices registered:

Wizard - Test notification

The transition to from step 3 to the Test notification dialog happens automatically in case a devices performs the registration, while looking at the Wizard.

Wizard: Step 4

For the supported SDKs the Unified Push Server has a feature to generate code snippets for the backend part as well:

Wizard - Backend integration hooks

The visible Java code above can be used in any JavaSE or JavaEE application that needs to send Push Notification requests to the Unified Push Server. Besides Java, the UI contains snippets for Node.js and cURL.

Wizard: Finished!

After all of that, you are done! Congratulations!

Wizard - Finished

Management of PushApplication

To work with a specific PushApplication, you have to select one from the overview list. However, to update the name or even deleting it, you have to click one of those links that are visible when hovering over the desired PushApplications:

PushAPplication - Overview

The Edit name option gives you a simple dialog, which accepts the new name:

PushAPplication - Rename

In order to remove the PushApplication, you have to confirm by entering the its name:

PushAPplication - Delete

When deleting a PushApplication, all Variants and their registered devices are removed!

Management of Variants

The Variants tab of the PushApplication gives a list of all existing variants. To edit or delete a Variant expand the details of the desired Variants (+).

Variant - Details

The above view shows details about the variant, such as the number of sent messages and registered devices. The view also contains more details about the involved 3rd party Push Network, GCM in this example. At the bottom the view also contains a list of all registered devices, showing their metadata.

To change the name of the variant, click on the Edit name link:

Variant - Rename

Similar to the PushApplication, in order to remove the variant, you have to confirm by entering the name of the variant:

Variant - Delete

To update the details of the used Push Network, such as the Apple certificate or the GCM key, click on Edit Network Options link:

Variant - Edit Push Network Options

It is also possible to renew the Variant Secret, used by the Mobile Applications running on the device:

Variant - Renew Variant Secret

When changing the variant secret or deleting it, existing mobile apps are no longer able to register their metadata on the Unified Push Server!

You have to confirm this change, as this requires updates to the mobile applications, running on the devices!

Managing registered device

The details view of a specific variant as a list of the registered devices at the bottom:

Device list

The table shows the metadata of each device, including the device token, subscribed categories or - if present - the used alias. On this screen you could also exclude a specific device from receiving Push Notifications, by unchecking the Receiving check-box.

Importing Device Metadata

For various reasons, e.g. migrating from a custom solution to the Unified Push Server, it is possible to import devices and their metadata, including their devicetoken, into a variant. This is possible via cURL and on the UI. For that, on a specific variant, click on the More menu you have the the choice to select the Import option:

Import UI

The following dialog allows you to upload a JSON file, containing the device metadata.

The API for the JSON importer is described here!

Import UI

Exporting Device Metadata

Similar, the Unified Push Server has an option to export the device metadata of a variant. This is handy when you want to move from one Unified Push Server instance to a different one. On the More menu of a specific variant, you have the the choice to select the Export option:

Export the tokens

Starting the export will generate a JSON file, which is being downloaded to your machine:

Export the tokens

Sending a Push Notification

The Admin UI allows you to send a (test) Push Notification to your Variants and their devices at any time. For that, open a PushApplication and click on the "Send Notification" button:

Send a Push

Now the Send Push dialog pops up:

Enter the payload

In the Send Push dialog, the Message text field contains the payload to be sent out to the 3rd party Push Network. To deliver the message click the Send Push Notification button.

It is possible to filter the list of receivers, using Alias, Device Types and Category. Read the Server Integration Tutorials for more details.

If all goes well, your message will be delivered by the 3rd party Push Network to your device:

You got a notification!

Sending a Push Notification from code

While sending a Push Notification from the AdminUI is a nice feature, in a real world scenario, the Push Notification is triggered by a backend, as explained in Server Integration Tutorials.

The Unified Push Server comes with APIs for Java and Node.js. Due to its RESTful architecture any backend, written in any language that supports HTTP(S), can send Push Notification requests to it. On the details page of a PushApplication you find the required Server URL and credentials (Application ID and Master Secret).

For the supported SDKs the Unified Push Server has a feature to generate code snippets for the backend part as well:

Backend push integration

Due to security reasons the Application ID and the Master Secret should be never stored on a mobile device! Push Notification requests should never be triggered directly from a mobile device.

The visible Java code above can be used in any JavaSE or JavaEE application that needs to send Push Notification requests to the Unified Push Server, like shown in the diagram below:

Sending Push from Backend

Besides Java, the UI contains snippets for Node.js and cURL.

PushApplication Analytics

The Unified Push Server provides some metrics and analytics which are presented on a dasboard :

Push Activity

The upper part shows some key numbers :

  • Push Messages : The total number of push messages sent to UnifiedPush Server for dispatching to registered devices.

  • Notification Dispatched : The total number of notifications dispatched via Push Networks to registered devices.

  • Notifications Opened : Number of notifications that were delivered to registered device and opened by a user.

  • Average Open Rate : The result of Notifications Opened / Notifications Dispatched

The Performance chart show for each Push Notification the number of targeted devices, the number of opened apps. The x-axis legend shows the alert value of the Push Notification payload.

Finally, the Push Networks chart shows the split between the different Push Networks.

To get the Notifications Opened metric activated, it needs to be "turned on" on the different client SDKs :

  • For iOS, please refer to this document.

  • For Android, please check the org.jboss.aerogear.android.unifiedpush.metrics package in the JavaDoc.

  • For Cordova, please refer to the Metrics section of this document.

  • For Windows, please refer to this document.

The collected metadata and payload is automatically deleted after 30 days, using a nightly job within the Unified Push Server.

PushApplication Activity

On the Activity log tab of a PushApplication you see a list of Push notifications that have been sent to the server:

Push Activity - Details

Each Push Notification can be expanded to see parts of the payload. While being in this view and opening the Send Push Notification Dialog to send a Push Notification, you will see the Pending…​ status afterwards, until the message was delivered to all involved 3rd party Push Networks:

Push Activity - Pending

The collected metadata and payload is automatically deleted after 30 days, using a nightly job within the Unified Push Server.

Next Steps

Now that you are familiar with the AdminUI of the Unified Push Server, you can learn about its Administrative UI here. If you want to dive straight into some mobile development, you can find a list of different tutorials and guides here.

Debugging the UnifiedPush Server

There are several ways to learn more about "What’s going on" inside the UnifiedPush Server

Enable Logging

The UnifiedPush Server internally uses java.util.logging as its logging framework.

WildFly and JBoss AS

There are different ways to enable detailed logging for the UnifiedPush Server in WildFly and JBoss AS.

Using jboss-cli tool

The most convenient way to enable logging on a running server is using the jboss-cli.sh (jboss-cli.bat on Windows) tool. Once the server is running, launch the tool:

$SERVER_HOME/bin/jboss-cli.sh --connect

Once connected to the server, paste in the following two commands, one by one:

/subsystem=logging/console-handler=AEROGEAR:add(formatter="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",autoflush=true)

/subsystem=logging/logger=org.jboss.aerogear.unifiedpush:add(level=FINEST,use-parent-handlers=false,handlers=["AEROGEAR"])

After each line you should notice a statement that your configuration was successful:

{"outcome" => "success"}
Tweaking the standalone.xml file

Another option is editing the $SERVER_HOME/standalone/configuration/standalone.xml file. NOTE: This requires a stop of the server.

Inside of the <subsystem> element of the logging subsystem you simply need to add the following XML snippet:

<console-handler name="AEROGEAR">
    <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
</console-handler>
<logger category="org.jboss.aerogear.unifiedpush" use-parent-handlers="false">
    <level name="FINEST"/>
    <handlers>
        <handler name="AEROGEAR"/>
    </handlers>
</logger>

Once done save the file and restart the server.

Test the enabled logging

At this point all log levels from the UnifiedPush Server are enabled. To verify this, you can send a Push Notification from the Admin Console. The console should print a message like:

17:30:50,571 FINE  [org.jboss.aerogear.unifiedpush.rest.sender.PushNotificationSenderEndpoint]
   (http--127.0.0.1-8080-1) Message sent by: 'AeroGear UnifiedPush Console'

Dashboard of the AdminUI

The AdminUI contains a Dashboard which provides a number of valuable information as well:

  • The Most Active section shows a recent list of PushApplications that have submitted Push Notification requests. Learn more here.

  • The Warnings section shows of a list of recent problems that occured. Learn more here

Integration

It is possible to integrate the UnifiedPush Server into your infrastructure, so that you can use code to setup the PushApplications and their variants. Due to the HTTP nature of the UnifiedPush Server all you need is an HTTP client that talks with the the server:

Creating a PushApplication

The above sequence diagram shows how to obtain an access token from Keycloak, which itself is used to authorize against the UnifiedPush Server for API calls, like creating a Push Application.

Since the UnifiedPush Server itself is protected using Keycloak, you need to use Keycloak’s Direct Access Grants Tokens in order to invoke the RESTful APIs of the UnifiedPush Server.

Migration Guide

The UnifiedPush Server supports a migration from older release to newer versions.

Supported versions

For the migration to our 1.0.3 release we are only supporting the 1.0.x series of the UnifiedPush Server:

  • 1.0.0

  • 1.0.1

  • 1.0.2

Database migration

We are supporting MySQL 5.5 and PostgreSQL 9.

Extract the unifiedpush-migrator-dist.zip from the release bundle to your desired location.

It is recommended to shutdown the application server, while performing the migration.

Below you find information on how to perform the migration on each of the supported databases.

PostgreSQL

Inside of the extracted zip file, there is a liquibase-postgresql-example.properties, copy that to liquibase.properties.

cp liquibase-postgresql-example.properties liquibase.properties

Once done, you need to edit the new file to match your database name and credentials.

MySQL

Inside of the extracted zip file, there is a liquibase-mysql-example.properties, copy that to liquibase.properties.

cp liquibase-mysql-example.properties liquibase.properties

Once done, you need to edit the new file to match your database name and credentials.

Run the script

After the liquibase.properties contains the proper credentials, you need to execute the migration tool:

./bin/ups-migrator update

In case of a successful run, the script prints

Liquibase Update Successful
If you want to get some more details on the actual migration steps, enable logging while performing the database migration:
./bin/ups-migrator --logLevel=DEBUG update

WAR file migration

After successfully executing the above database migration script you need to replace the deployed 1.0.x WAR files with the new ones and start the application server.

In case of any error, please contact us on our [mailing list](https://github.com/aerogear/aerogear-unifiedpush-server#project-info)!

Next steps

Now that you are familiar with the UnifiedPush Server it is time to checkout out our tutorials to get Push Notification working with our mobile clients and existing backends!

Client Integration Tutorials

Different type of client technologies are supported with the Server

Server Integration Tutorials

For the backend integration of your server we have a few different tutorials as well:

More demos

Appendix

This section contains a few diagrams, that explain the architecutre and the work-flow of the UnifiedPush Server

Global Architecture

This diagram show the different components that compose the UnifiedPush Server:

Global Architecture

The UPS Core contains a DAO layer, talking to the (MySQL/Postgres) database. The DAO layer is invoked by different service classes. The message delivery to the different Push Networks is handled by JMS (see here for more details). The access to the server is handled via two different categories of RESTful APIs.

REST APIs

Core APIs

The UnifiedPush Server is not limited to be accessed only via the UI for creating PushApplications or Variants. The RESTful Core APIs (e.g. Management/Metric APIs) offer access to the server for integration cases like discussed in the UPS Integration section or below:

Creating PushApplication from code

Developer APIs

The Developer APIs are more commonly used. They offer public endpoints for device registration and sending Push Notification delivery requests.

Device Registration

Below is a diagram that explain the flow of the Device Registration Process:

Device Registration

When the mobile device obtains a device token (or registrationID) from its PushNetwork (e.g. GCM or APNs), the AeroGear powered application calls our Registration SDK with the given token. The SDK itself authenticates itself against the UnifiedPush Server and sends the token to the server, so that it can be used for future Push Notification sends.

Sending a Push Notification

The UnifiedPush Server comes with APIs for Java and Node.js. Due to its RESTful architecture any backend, written in any language that supports HTTP(S), can send Push Notification requests to it:

Sending Push from Backend

If the backend needs to send a push notification, e.g. after catching an event, the AeroGear Push Sender SDK is invoked. SDK itself authenticates itself against the UnifiedPush Server and sends the payload to it. This results in several JMS jobs, that are than delivering the payload to the 3rd party Push Networks. Eventually the message may hit the device, delivered from the 3rd party Push Network.

JMS internals

Currently the delivery of Push Notifications is handled with CDI events and JMS.

CDI events are translated into JMS messages so that they can be processed asynchronously and transactionally (if needed).

Token Loading and Notification Dispatching

There is architectural diagram describing how different processors works internally:

JMS details of the UnifiedPush Server

Once the payload hits the RESTful endpoint, a NotificationRouter is invoked, which queues a JMS message into {Network}PushMessageQueue, one for each Variant in the given Application. Once these messages are queued, the REST interface replies 202 Accepted, which indicates that the Push Message was accepted for later processing.

Messages from {Network}PushMessageQueue are then processed by TokenLoader transactionally. TokenLoader streams device tokens from database and pushes token batches of configured size (aerogear.{network}.batchSize system property) to {Network}TokenBatchQueue. The TokenLoader loads number of batches to load in one transaction (configurable by aerogear.{network}.batchesToLoad system property). After one token loading transaction, TokenLoader sends a message back to same {Network}PushMessageQueue with information from which token should next transaction continue. The TokenLoader transaction can also fail when memory limits of {Network}TokenBatchQueue are exceeded. In that case, the token loading transaction will be repeated (the batches are de-duplicated by their serial ID, so in that case there will be no duplicate batches).

The tokens from {Network}TokenBatchQueue are received by NotificationDispatcher that opens connection/-s to a given Push Network and submits Push Messages for the given batch of tokens. The number of NotificationDispatcher workers can be limited by configuring maxSession activation config properties of Message-Driven Beans.

maxSession activation config property for MDBs influences how many workers can be instantiated on given node, so this does not limit number of workers in a cluster of nodes.

Once NotificationDispatches finishes processing for given batch of tokens (no matter if it succeeds or fails), it triggers MetricsCollector that writes metric into database.

Metric Collection

The further details on metric collection process can be seen in the following diagram:

JMS details of the Metric Collection

Once TokenLoader loads a batch and sends it for processing, it also queues messages to BatchLoadedQueue. Once it loads last token batch, it also queues message to AllBatchesLoadedQueue. These events are important for MetricCollector to decide whether token loading process ended.

NotificationDispatches sends metrics for each processed message to MetricQueue.

Both, TokenLoader and NotificationDispatcher sends message to TriggerVariantMetricQueue. That messages are processed by MetricCollectionTrigger that receives them, deduplicates and sends exactly one message to TriggerMetricCollectionQueue.

MetricCollector is triggered by message from TriggerMetricCollectionQueue. It receives it transactionally, and if it detects that Push Messaging processing is still in progress, it will roll that transaction back, which means that it will be redelivered (the time after it is redelivered can be configured in JMS queue properties).

MetricCollector internally collects messages from MetricQueue and BatchLoadedQueue, updates PushMessageInformation object and writes it into database. Once MetricCollector receives message from AllBatchesLoadedQueue and it detects, that metrics were processed for all loaded batches, it ends Push Message metrics collection process by committing its transaction.

Limiting Number of ApnsServices

APNs limits how many connections can be created for one iOS variant. In order to make sure that the number of opened connection won’t exceed that limit, UnifiedPush Server manages distributed counter of available (free) service slots. The counter is stored as messages in FreeServiceSlotQueue, so each message in that queue represents one available slot for a new service that can be used to open connection to APNs.

FreeServiceSlotQueue is populated in NotificationRouter with number of messages representing limit of connections that can be created.

Once NotificationDispatcher wants to push messages to APNs leveraging ApnsService, it will first ask ApnsServiceHolder for an instance of service. ApnsServiceHolder provides a cached instance or it asks for a slot for a new service instance, then it can create it.

When the notifications are dispatched, NotificationDispatches returns instance of ApnsService to ApnsServiceHolder that stores it to a cache for reuse by another dispatcher, and if not reused within time limits, it closes allocated connection and sends a messages to FreeServiceSlotQueue indicating that a new instance can be created.

JMS details of the ApnsServiceHolder

redhatlogo-wite