Using the Push Notifications Mobile Service

Introduction to the Push Notifications Service

Overview

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 provides, which eventually might deliver the message to the physical device.

Variant

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

APNs

Apple Push Notification service.

Installation

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

Prerequisites

Setting Up the Identity Management 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 guide to enable push notifications for your Xcode project.

  2. Follow the official 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. Click Add to Project and choose Browse Catalog from the options.

    You can filter the catalog items to only show mobile specific items by clicking 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.

Binding a Mobile Client with the Push Notifications service

Prerequisites

Android
  • A Google account

  • Access to the Firebase console. See Firebase Setup to get started.

iOS
  • An Apple Developer account

  • An APNs client TLS certificate. Have a look at APNs Setup for further instructions.

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 once it’s done, your mobile app can use that service immediately.

The association between a Mobile Client and Push Notifications Service uses the Service Broker bind feature.

To associate a Mobile Client with a mobile service:

Procedure

  1. Navigate to the Overview of your OpenShift project.

  2. Click on the Mobile Client and navigate to Mobile Client view.

    Your mobile app will be represented by two items in OpenShift, an item in the Mobile Clients list and an item in the Provisioned Services list. Make sure to click on the item in the Mobile Clients list.
  3. Navigate to Mobile Services tab.

    mobile clients services all unprovisioned
  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.

Android

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.

iOS

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 next specific additional instructions depending on your platform:

Android

Locate this file at the following location in your application project:

app/src/main/assets/mobile-services.json

iOS

Locate this file at the following location in your application project:

<app directory>/mobile-services.json

Cordova

Locate this file in your application project and import it using require.

const aerogearConfig = require("./mobile-services.json");

Alternatively you can create a JavaScript object and use directly:

const aerogearConfig = /* Paste here the contents of the clipboard */;
Xamarin

Locate this file at the following location in your application project:

Resources/mobile-services.json

Setting up Push Notifications service SDK

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

Prerequisites
Android

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

iOS

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

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

    implementation "org.aerogear:aerogear-push:1.0.0"
    implementation "com.google.firebase:firebase-messaging:[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 'com.google.gms:google-services:[version]'
          }
      }
  4. Apply the plugin in your app build.gradle file

      // ADD THIS AT THE BOTTOM
      apply plugin: 'com.google.gms.google-services'
iOS
  1. Add the dependency to your Podfile

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

    $ pod install
  3. Import the SDK

    import AGSPush
Cordova
  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
Xamarin

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.

Android
  1. Getting an instance of the PushService

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

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

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
    });
});
Xamarin

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 it 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.
Android

Add to your project an implementation of MessageHandler:

public class MyMessageHandler implements MessageHandler {

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

}

Add it to your application’s manifest.

<meta-data
    android:name="DEFAULT_MESSAGE_HANDLER_KEY"
    android:value=".MyMessageHandler" />
iOS

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

Cordova

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

Xamarin

This feature is not yet supported in the AeroGear Xamarin SDK