PushServiceManager

Class Overview

PushNotification service.

This service is responsible for registering the application with the Operating System Push-Notification service.

Overview

Push notifications are a service you can use to broadcast information (notifications) from a server to the user of your mobile applications. These notifications may be simple messages or more complex data for the application. Notifications can be received even if the application is not currently running. They can appear in various forms, the most common is a message in the phone's notification center that can be accessed by scrolling down the status bar on both Android phones and iPhone.

Push notification involves three parts:

• a mobile device
• a push notification service which is platform dependent (FCM, APNs, MPNS)
• a 3rd party application server (your web service)

Platform portal:

• If you do not already have a developer account for the desired plateform(s), then you will need to create one first for each platform (NB. some developer account may require a paid subscription)
• Register your application on each platform using your developer account
• Save the certificate for the third party server, and the certificate and identifier for the application
• Install and set up

How to broadcast:

• When the 3rd party application server needs to send a notification to a mobile device, it sends a message to the associated push notification server using the correct registration id
• If the message is valid, the push notification server sends the notification to the mobile device that handles it

How to receive:

The following two steps are required to receive push messages:

• The application must register with the platform notification service and will then receive a registration ID
• The application must send the registration ID and its device identifier to the third party server

Push Service Registration

Requirements

Android

The Firebase Cloud Messaging service is used.

In order to use this service, you need to create a Firebase project as described in the official documentation.

Note that the configuration of the Android project is done by NeoMAD, the only things you need to provide is the google-services.json file which can be obtained in the Firebase portal of the application.

iOS

The Apple Push Notification Service is used.

In order to use this service, you should refer to the official documentation.

To sum up, the process is as follow :

• create a specific application ID with the specific bundle ID (you cannot use a wildcard bundle ID if you are planning to use push notifications).
• create and install a new provisioning profile that contains the App ID you registered for APNs. Use this profile to sign the application.
• export SSL certificate and key from this provisioning profile and install it on the 3rd party application server.
• use this certificate to communicate between your 3rd party application server and APNs servers.

NB. In order to test an iOS application using APNs, you cannot use the simulator but a physical device.

URS declarations

In order for an application to be able to receive push notifications, the URS must declare the pushservice tag. This will indicate to NeoMAD that the application uses push notifications.

• For iOS just declare pushservice, empty

 <pushservice />
 

• For Android, complete the googleServices parameter

 <pushservice googleServices="path_to_google_services_json"/>
 

The pushservices section of the URS automatically handles the required permissions declarations.

Device registration to push service

To be able to receive push notifications through the application, the device where the application is running must register to the push notification service. This can be done in the application whenever you want using PushServiceManager:

 // Get the default NeoMAD PushServiceManager instance
 PushServiceManager manager = PushServiceManager.getDefault();
 // Register the device to the push notification service
 manager.register();
 

This will register the device to the push service whatever is its platform.

The push service will transmit a registration identifier to the device. This identifier must be use by your third party server to send push notifications to the device. Consequently, the application must transfer the identifier to the server, via a https connection for example, in order to be able to receive push notifications. The identifier can be accessed thanks to getCurrentID().

 if (manager.isRegistered()) {
    // Get the device push service registration identifier, if the device is registered
    String identifier = manager.getCurrentID();
 }
 

NB. The modification of the service registration status can be followed by overriding onPushRegistrationChanged(int, String).

Message reception

Get the push message data

Once the device is registered to the push service, it can receive push messages from a third party server for example. To do so, simply override onPushMessageReceived(PushMessage). The PushMessage will contain all the information sent by the server. Up to you to present the information to the user.

Data presentation limitation

Be aware that the application can receive the push message whereas it is in background. In that case, calls to UI or life cycle methods may cause the application to crash or to have unexpected behavior. To present data to the user from push message, prefer the usage of Notification. If the data does not need to be presented to the user immediately, prefer to save them in the preferences or in files and load them when the application restarts.

Summary

[Expand] Inherited Methods

From class java.lang.Object boolean equals(Object obj) Indicates whether some other object is "equal to" this one. final Class<?> getClass() Returns the runtime class of an object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeout, int nanos) Causes current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long timeout) Causes current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. final void wait() Causes current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object.