Using the Push Notifications Mobile Service

Introduction to the Push Notifications Service


The Push Notifications service allows you to send native push notifications to different mobile operating systems.

  • Code once and push notifications to iOS and Android

  • Push notifications to defined groups

  • Push notifications to either iOS only or Android only

  • Push notifications to different variants of a mobile app

  • Push notifications from different back-end apps to the same mobile app

Currently the service supports:

Push Notifications Terminology

This section describes terminology that is associated with Push Notifications.

Push Application

A logical construct that represents an Mobile App, for example, Mobile HR.

Push Notification Message

A simple message to be sent to a Push Application.

Sender Endpoint API

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


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


Apple Push Notification service.


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

Administrative User Interface

(AUI) The Unified Push Admin UI Web UI that allows you manage Push Applications and Variants, view statistics and send Push Notifications to devices.

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 send any 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.

How the UnifiedPush Server Works

The Push Notifications service offers a unified Notification Service API to the above mentioned Push Network Services. It can be seen as a broker that distributes push messages to different 3rd party Push Networks.

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).


Setting Up the Push Notifications Mobile Service

Obtaining Firebase Cloud Messaging Credentials

Before the Android application is able to receive the notifications, you must set up access to Firebase Cloud Messaging. As with iOS, you are only able to test out your push notifications in a real device. The following credentials are necessary to set up Firebase Cloud Messaging for your app:

  • the Server key

  • the Sender ID

  • the google-services.json file containing the credentials required to connect your app to Firebase and Google services.

    1. From the Project Settings screen, switch to the Cloud Messaging tab, where you can find the Server key and Sender ID (known in GCM as Project Number). There is also a Legacy server key but it should not be used for new projects.

    2. Download the google-services.json file as described in the Google Documentation.

Enable Push Notifications for iOS App

The following guide helps you to enable Push Notifications for your iOS application.

  1. Follow the official Apple guide to enable push notifications for your Xcode project.

  2. Follow the official Apple guide to generate an APNs client TLS certificate and export the client TLS identity from your Mac.

    Make sure to protect the p12 file with a password.
    The exported p12 file with the password will be used later when binding your Mobile Client to the Push Notifications.

Provisioning Push Notifications Service

To provision the mobile service:

  1. Log into the OpenShift console.

  2. Create a new project or choose an existing project.

  3. Select Catalog from the left hand menu.

    You can filter the catalog items to only show mobile specific items by selecting the Mobile tab.

  4. Click Services and choose the service.

    catalog mobile services
  5. Follow the wizard for provisioning that service.

    If prompted to Create a Binding, choose Do not bind at this time.

Once the wizard steps are completed, navigate to the Project Overview in OpenShift to see the newly provisioned service. Provisioning a service may take some time.

Binding a Mobile Client with the Push Notifications service


  • A Google account

  • Access to the Firebase console. Refer to Firebase Docs.


To use mobile services, you must represent your mobile app in OpenShift using a Mobile Client, and that Mobile Client must be associated with the mobile service. This association is called binding and it is necessary for your mobile app to use that service.

To bind a Mobile Client with a mobile service:


  1. Navigate to the Overview of your OpenShift project.

  2. Select the Mobile Client name listed in the Mobile Clients section.

  3. Navigate to Mobile Services tab.

    mobile clients services all unbound
  4. Click Create Binding and follow the Create Binding wizard to associate the Mobile Client with the Push Notifications Service.

  5. Fill out the binding parameters required by the Push Notifications Service.

When you bind a mobile client to the Push Notifications service, a variant is created to store the credentials required to communicate with a push network. Those credentials need to be provided in the binding dialog.

First pick your Mobile Client Type. Depending on the selection you then have to fill out the fields for either Android or iOS.


You need to provide a Server Key and a Sender ID. Both can be found in the Firebase console under Project Settings > Cloud Messaging. Make sure that you have selected Android in the Mobile Client Type dropdown.


You need an APNs client TLS certificate. Have a look at APNs Setup for instructions on how to obtain one. Make sure that you have selected iOS in the Mobile Client Type dropdown. The certificate needs to be encoded in base64 before copying it into the field labelled iOS .p12 file. If you’re on Mac OS run:

cat <path/to/your/.p12> | base64

If you’re on Linux chances are that you’re using a version of the base64 tool that does line wrapping. You need to disable this:

cat <path/to/your/.p12> | base64 --wrap=0

After clicking Bind your variant will be created in UPS and you should see a new binding for your mobile client.

Configuring your Development Environment for the Push Notifications Service

Downloading the Mobile Services Configuration File

  1. Navigate to your project in OpenShift.

  2. On the Overview screen, expand your Mobile Client to view the CLIENT INFO.

  3. Copy the configuration to your clipboard.

  4. Save the contents of the clipboard to a new file called mobile-services.json.

    The mobile-services.json file is the link between your provisioned services on OpenShift and the mobile app you are developing. This file provides all required configuration to initialise the various SDKs and get them hooked up/connected to the back-end services.
  5. Follow the platform-specific instructions:


Move mobile-services.json to the following location in your application project:



Move mobile-services.json to the following location in your application project:

<app directory>/mobile-services.json

Ensure that mobile-services.json is a member of the project in the Xcode Project Navigator.

Move mobile-services.json to the following location in your application project:



Move mobile-services.json to the following location in your application project:


Setting up Push Notifications service SDK

This guide will help you to set up the Push Notifications service SDK in your App.


You need a Firebase account. See Google setup to get started.


You need to set up APNs. See Apple setup to get started.

Importing the libraries
  1. Add the push dependency to your application module

    implementation "org.aerogear:aerogear-push:1.0.0"
    implementation "[version]"
  2. Create a new project in Firebase console

  3. Add The Google Services Gradle Plugin in your root build.gradle file

      buildscript {
          dependencies {
              classpath '[version]'
  4. Apply the plugin in your app build.gradle file

      apply plugin: ''
  1. Add the dependency to your Podfile

    target '[TARGET NAME]' do
        pod 'AGSPush', '[VERSION]'
  2. Update the dependencies

    $ pod install
  3. Import the SDK

    import AGSPush
  1. Install cordova-plugin-aerogear-push:

    $ cordova plugin add @aerogear/cordova-plugin-aerogear-push
  2. Ionic Apps require an additional dependency, the Ionic Native Push Library

    $ npm install --save @ionic-native/push
  3. Install the Unified Push Server package needed for device registration:

    $ npm install --save @aerogear/push

This feature is not yet supported in the AeroGear Xamarin SDK

Device registration

To make use of the Push Notifications service, devices need to be registered by calling an endpoint of the server. The SDKs will handle this for you and the following steps will give you everything you need to start working with push notifications.

  1. Getting an instance of the PushService

    PushService pushService = new PushService.Builder().openshift().build();
  2. Registration request

      .requestOn(new AppExecutors().mainThread())
      .respondWith(new Responder<Boolean>() {
        public void onResult(Boolean value) { // Yay }
        public void onException(Exception exception) { // Oops! }
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    var config = UnifiedPushConfig()
        success: {
           print("Successfully registered to Unified Push Server")
        failure: { (error: Error!) in
           print("Failure to register for on Unified Push Server: \(error)")

Using plain Cordova

const push = PushNotification.init({
    android: {},
    ios: {
        alert: "true",
        badge: "true",
        sound: "true"

// Registration handler
push.on('registration', data => {
    // PushRegistration is part of @aerogear/push
    new PushRegistration().register(data.registrationId).then(() => {
        // Registration with UPS successful, you can now send push notifications from the UPS UI
    }).catch(err => {
        // Error on device registration

Using Ionic

import { Push } from "@ionic-native/push";

const pushObject = new Push().init({
    android: {},
    ios: {
        alert: true,
        badge: true,
        sound: true

pushObject.on('registration').subscribe(data => {
    new PushRegistration().register(data.registrationId).then(() => {
        // Registration with UPS successful, you can now send push notifications from the UPS UI
    }).catch(err => {
        //Error on device registration

This feature is not yet supported in the AeroGear Xamarin SDK

Accessing Push Notifications using the Unified Push Admin UI

The Unified Push Admin UI allows you to send Push Notifications.

To access Push Notifications using the Unified Push Admin UI, you will need to:

  • Make sure the Push Notifications service is provisioned.

  • Select a route in OpenShift.

  • Login with your OpenShift credentials.

On first login you need to provide the OpenShift OAuth service permissions to read your user account.

Additional Information

  • To access Push Notifications using the RESTful endpoints, see the API documentation.

Sending a Push Notification

The Unified Push Admin UI allows you to send push notifications to devices.

  1. Open the Unified Push Admin UI in a browser.

  2. Select the target application from the home page and click Send Notification To This App.

    Send a Push
  3. When the Send Push dialog displays, enter text in the Message form.

    Enter the payload
  4. Click Send Push Notification to send the message to the target application.

    You got a notification!
The 3rd party Push Network is responsible for delivering the Push Notification to the target application.

Handling Push Notifications

Follow the next steps to handle incoming push notifications in your foregrounded application.

push notifications that arrive when the application is in the background will always be handled by the OS.

Add to your project an implementation of MessageHandler:

public class MyMessageHandler implements MessageHandler {

    public void onMessage(Context context, Map<String, String> message) {
        // Handle incoming message


Add it to your application’s manifest.

    android:value=".MyMessageHandler" />

The AeroGear SDK for iOS does not provide a way to handle incoming messages. Instead, follow the Apple’s official documentation about notifications.


The AeroGear SDK for JavaScript does not provide a way to handle incoming messages. We recommend using the Ionic Push plugin.


This feature is not yet supported in the AeroGear Xamarin SDK