< Table of Contents

Configuring Mobile Client Notifications

You can configure the Gateway to support mobile app messaging notifications using Firebase Cloud Messaging (FCM) and the jms service. This feature enables you to notify users that messages are awaiting them when their Kaazing mobile app is in the background on their device.

Here is an example of the production topology for supporting mobile app notifications with the Gateway:

Figure 1: Supporting Mobile Apps with Firebase

This document contains the following sections:

Notification Process

Once the Backend Service is configured with the user ID and corresponding device tokens for each user, the following notification process can occur:

  1. The Backend Service receives an update such as a stock trade.
  2. The Backend Service creates a message to be sent as a notification for a user. The message is created using a persistent store containing user-specific information, and using custom properties such as device tokens, notification sound, etc.
  3. The Backend Service sends a message to the Message Broker using a designated JMS queue. The message contains the user ID and device information for each user.
  4. The Gateway, which is subscribed to the same notification queue, receives the message posted by the Backend Service via the Message Broker.
  5. If the notification message has the special notification properties set, the Gateway sends a notification to Firebase Cloud Messaging (FCM). If more than one device token is specified, the Gateway sends a multicast notification to FCM.
  6. Firebase sends a message notification to Mobile Client devices. If the Kaazing JMS app on the device is in the background, and notifications are enabled for the app, the device notifies the user that there is a new message.
Notes:
  • Notifications are only supported from the jms and ibmmq services in Kaazing Enterprise Gateway 5.x.
  • Notifications for iOS 8.4 and later are supported.
  • Notifications for Android API Level 23 and later are supported.
  • The notification payload is limited to a maximum of 2KB. If the notification payload is more than 2KB, the Gateway will log a warning.
  • Developers must add iOS apps to a Firebase project to be able to receive Apple Push Notification Service (APNs) notifications via Firebase on their iOS devices.
  • The Gateway only supports downstream notifications, from the Gateway to the client device via FCM over XMPP.

Components

The exact components involved in your Kaazing mobile client notification deployment depends on how you decide to collect the JMSXUserID and Firebase registration tokens. The following table lists the components involved in the recommended deployment.

Component Description
Kaazing WebSocket Gateway 5.x Enterprise Edition The Enterprise Edition contains the jms and ibmmq service needed for mobile client notifications. For more information, see kaazing.com/download.
jms and ibmmq service on Gateway The jms or ibmmq service is configured on the Gateway to support messaging between the mobile clients and the JMS broker. For more information, see JMS Services for Kaazing Gateway and About Integrating Kaazing Gateway and JMS-Compliant Message Brokers.
Mobile clients Objective-C (iOS) or Android devices that can receive notifications.
Firebase Cloud Messaging (FCM) Firebase must be added to your iOS and Android mobile clients to receive notifications from the Gateway. Once you have added Firebase, your app will use FCM to receive notifications. For information on adding Firebase, see Setting Up a Firebase Cloud Messaging Client App on iOS or Set Up a Firebase Cloud Messaging Client App on Android from Firebase.
Firebase registration device tokens To verify that they can send and receive messages, client apps must register with Firebase Cloud Messaging (FCM). In the Kaazing mobile client notification process, the client obtains a unique registration token from Firebase and sends a message to a registration queue via the Gateway. A backend service subscribed to that queue stores the token for later use when sending notification messages. For more information, see Registering Client Apps.
Backend Service The Backend Service is the notification publishing service. The service must be able to store the user ID and Firebase device token mappings and send notifications to the JMS Broker using those mappings on designated notifications queues. The service must subscribe to a user details queue to receive messages containing the user IDs and Firebase device tokens.
JMS Broker The JMS Broker used to send and receive messages between the backend service and the Gateway.
Registration JMS queue When a Kaazing mobile client first launches it will send a message to a registration queue configured on the JMS broker to provide the backend service with the user ID and Firebase registration device token. The user ID is included in the standard JMSXUserID property and the device token is included in a custom property of the message. The backend service is subscribed to the queue to receive and store the user ID and device token.
Notification JMS queue When the backend service wants to send a notification, it sends a notification message to one or more notification queues configured on the JMS broker. The Gateway receives the notification message and then uses Firebase to notify the mobile client.
JMSXUserID The JMS message property used to collect the user ID. JMSXUserID is applied to the registration queue used to collect user and device information. For security reasons, the JMSXUserID property is set on the Gateway.
LoginModule For security reasons, it is preferable that the Gateway set the JMSXUserID property on the message instead of the client. To be able to accomplish this, a LoginModule is configured on the JMS service hosted by the Gateway. For more information on Login Modules, see Configure a Chain of Login Modules and Configuring User Auditing.

Deployment and Testing Process

Here is an overview of setting up mobile app notifications with the Gateway:

Step Description Reference
1 On the JMS broker, set up a designated registration queue to receive messages from mobile clients via the Gateway that contain their Firebase device tokens and user IDs. JMS Broker Configuration
2 On the JMS broker, set up a designated notification queue. The notification queue is used as follows:
  • The backend service publishes notification messages to the queue.
  • The Gateway subscribes to the queue to receive notification messages.
JMS Broker Configuration
3 On the JMS broker, set up a designated error queue. The backend service will monitor the error queue. The Gateway publishes messages to the error queue if a notification cannot be sent to a particular device. The name of the error queue should be specified in the Gateway configuration file and should be given the privileges to publish messages to the error queue. Error Queue
4 Set up the backend service with a persistent store for the JMS user IDs and Firebase device tokens. Subscribe the backend service to the designated JMS registration queue. Backend Service Configuration
5 Configure the jms or ibmmq service on the Gateway to support notifications. The service contains configuration elements that specify all notification-related information. JMS Broker Configuration
6 Integrate Firebase for Cloud with your Kaazing mobile apps. Firebase Configuration for Mobile Clients
7 Launch a Kaazing Mobile Client in order for the client to post a message to the user detail queue via Gateway containing their Firebase device tokens. The Gateway will then add the user ID, and submit the message to the Message Broker. The Backend Service is subscribed to the user details queue and receives the user ID and Firebase token for mapping and storage.  
8 Have the Backend Service send a notification message to the notification queue using the user ID and Firebase token is has stored.  
9 Ensure that the Kaazing mobile client app is in the background and that notifications are enabled. Verify that the device receives a notification message.  

JMS Broker and Backend Service Configuration

Configure and deploy the JMS broker as the first step in deploying Kaazing client mobile notifications. Once the JMS broker is set up, the backend service can be configured to receive user ID and device token information from the JMS broker via a designated queue and then send notification messages to users via notification queues.

JMS Broker Configuration

Configure the JMS Broker as follows:

  1. Registration Queue: Create a designated registration queue for receiving user ID and Firebase device tokens. When the Kaazing JMS client first launches, it will send a message to this queue that contains its user ID and Firebase device token as message properties.
  2. Notification Queues: Create one or more designated notification queues, for example, NOTIFICATIONS_BANKERS, NOTIFICATIONS_CUSTOMERS, etc. These queues are used by the backend service to pass information such as user ID, device tokens, sound, and badge number as custom properties of a message sent as a notification.
  3. Error Queue: Create an error queue to notify the backend service of unsuccessful notifications. When the backend service receives messages from the error queue, it can determine what the best response is to perform.

Later in the deployment, the JMS service in Kaazing Enterprise Gateway will be made aware of the names of designated notification queues and the names of the custom properties so that it can subscribe to them.

Backend Service Configuration

Your backend service needs to perform the following actions to support mobile client notifications:

  1. Client registration: The backend service must subscribe to the registration queue to receive messages from Kaazing mobile clients containing their user IDs and device tokens. When new messages arrive on the registration queue, the backend service can create a mapping between the JMSXUserID and the corresponding device tokens which can then be cached using persistent storage.
  2. Notification messages: For notifications, the backend service posts messages to the notification queue on the JMS broker. The backend service must use the collected JMSXUserID and corresponding Firebase registration tokens, and pass them to the JMS broker as custom properties of the notification message.
  3. Error messages: For unsuccessful notifications, set up a designated error queue. The backend service will monitor the error queue. The Gateway publishes messages to the error queue if a notification cannot be sent to a particular device. The name of the error queue should be specified in the Gateway configuration file and should be given the privileges to publish messages to the error queue. For more information, see Error Queue.

Notification Queue Message Properties

When the backend service publishes messages to designated notifications queues it may set the message properties described in this section. The property names can be customized using the service property named in the Service Property column. The Message Property column gives the default name. Only the device token property (FIREBASE_DEVICE_TOKENS) is required.

In table below, there are two types of properties: message property (for example, NOTIFICATION_COLOR) and its corresponding Gateway service property (for example, color.property.name).

For example, the default property for text color is NOTIFICATION_COLOR. To specify text color for a message using the default NOTIFICATION_COLOR property, do the following:

   textMessage.setStringProperty("NOTIFICATION_COLOR", "#E04006");
  

To change the property for text color to something else, modify the service property like this:

   <color.property.name>COLOR</color.property.name>
  

And then change the code that sets the text color like this:

   textMessage.setStringProperty("COLOR", "#E04006");
  
Service Property Message Property Type Details
device.tokens.property.name FIREBASE_DEVICE_TOKENS String Comma separated list of device tokens. If not specified, a notification will not be sent and a message will be published to error.queue (if configured).
badge.number.property.name NOTIFICATION_BADGE_NUMBER Integer Badge number (number of waiting notifications) to be shown on the app.
color.property.name NOTIFICATION_COLOR String Format #RRGGBB.
icon.property.name NOTIFICATION_ICON String For Android, this property indicates the notification icon. It sets the value to a drawable resource in the client project.
sound.property.name NOTIFICATION_SOUND String Name of the sound file that is packaged in the app. The sound is played on the device when the notification is delivered. The default value is default. The default value included in the JSON payload is “default”.
title.property.name NOTIFICATION_TITLE String The notification message title.

The Gateway is made aware of the names of the special custom properties via the JMS service configuration on the Gateway. If the configuration for property names are not specified, then the Gateway uses the corresponding default property names.

Firebase Configuration for Mobile Clients

In the Kaazing mobile client notifications deployment, Firebase is used by the Gateway to turn JMS notification messages into Firebase notifications that are sent to mobile clients configured for Firebase. A standard Firebase configuration is used.

To configure your Kaazing JMS app to use Firebase, do the following:

  1. For iOS, do the following steps to configure the app to receive notifications from APNs directly and from Firebase:
    1. Use Apple Developer Member Center to create an explicit AppID with Push Notifications enabled.
    2. Use Apple Developer Member Center to create a client SSL certificate specifically for the AppID.
    3. Download and add the certificate to the keychain. Export the certificate in .p12 format from the keychain.
    4. Use Apple Developer Member Center to create a new provisioning profile for the AppID created earlier. Download the profile and install it in the iOS device.
    5. Follow the steps in the Setting Up a Firebase Cloud Messaging Client App on iOS from Firebase.
  2. For Android, follow the steps in the Set Up a Firebase Cloud Messaging Client App on Android from Firebase.

Once your client has Firebase installed and configured, it can receive Firebase messages from the Firebase console. To enable your app to receive messaging notification via the Gateway, proceed to the next step.

Kaazing WebSocket Gateway Configuration

For Kaazing mobile client notifications, there are two processes involving the JMS service on the Gateway:

The following steps provide the Gateway configuration settings to support both processes.

Note: Only one JMS service is required to support both registrations and notifications.

JMS (or IBMMQ) Service Configuration

A standard JMS service configuration (a jms or ibmmq service) supports Kaazing mobile client messages to the registration queue. Notification messages require that you configure notification-specific elements in the JMS service.

To send a notification using Firebase, the jms or ibmmq service is configured with the following information:

When the Gateway starts, it subscribes to all notification queues and dispatches notifications for the incoming messages using the custom message properties. The JMS service configuration elements are described in Notification Properties for JMS Service.

To provide the Gateway with the necessary Firebase information, the JMS service notifications configuration element specifies all notification-related information. The notifications configuration element is a child of the JMS service properties element.

JMS service with Notifications Example

The following JMS service example illustrates the properties for integrating Firebase notifications.

<service>
  <name>JMS Service</name>
  <description>JMS Service</description>
  <type>jms</type>

  <properties>
    <notifications>
      <firebase>
        <server.key>jUtz-oGeIk3R</server.key>
        <server.hostname>fcm-xmpp.googleapis.com</server.hostname>
        <server.port>5236</server.port>
        <sender.id>163072308877</sender.id>
        <device.tokens.property.name>FIREBASE_DEVICE_TOKENS</device.tokens.property.name>
      </firebase>
      <notification.queues>
        NOTIFICATIONS_BANKERS
        NOTIFICATIONS_CUSTOMERS
      </notification.queues>
      <error.queue>NOTIFICATION_ERROR</error.queue>
      <badge.number.property.name>BADGE</badge.number.property.name>
      <color.property.name>COLOR</color.property.name><!-- The color is in format #RRGGBB-->
      <icon.property.name>ICON</icon.property.name>
      <sound.property.name>SOUND</sound.property.name>
      <title.property.name>TITLE</title.property.name>
    </notifications>
    ...
  </properties>
  ...
</service>

Here is a simplified example without any of the optional properties.

<notifications>
...
  <firebase>
    <sender.id>163072308877</sender.id>
    <server.key>AIzaSyD_fYqS9jUtz-oGeIk3RGNbQebNvngYu_s</server.key>
    <device.tokens.property.name>FIREBASE_DEVICE_TOKENS</device.tokens.property.name>
    
    <notification.queues>
    NOTIFICATIONS_BANKERS
    NOTIFICATIONS_CUSTOMERS
    </notification.queues>
    
    <error.queue>NOTIFICATION_ERROR</error.queue>

  </firebase>
...
</notifications>

Notification Properties for JMS Service

The following JMS service properties are used to integrate the Gateway with Firebase.

Property Required or Optional? Description
notifications Required Parent element of all notifications properties. A child of the properties element.
firebase Required Parent element of all properties relating to Firebase (the following five properties marked in blue). A child of the notifications element.
server.key Required Firebase server key used to establish a secure connection between the Gateway and the FCM servers. To locate your Firebase server key, in Firebase, click Project Settings, then click on the Cloud Messaging tab. The key is located under Server Key.
server.hostname Optional The hostname of the Firebase server. The Gateway must be able to resolve this hostname using DNS. By default, the value of server.host is fcm-xmpp.googleapis.com but you can specify a different hostname for testing purposes.
server.port Optional The port number for Firebase service on the Firebase server. The production environment default value is 5235. The testing environment default value is 5236.
sender.id Required The Firebase sender ID is used to establish a secure connection between the Gateway and the FCM servers. It can be found in the Firebase Console. In Project Settings, click Cloud Messaging.
device.tokens.property.name Optional The name of the message property used to specify the device token or tokens to which a notification is to be sent. Default is FIREBASE_DEVICE_TOKENS.
notification.queues Required Lists the names of the designated notification queues. These are the same queues to which the backend service is sending messages. The Gateway subscribes to these queues and receives messages sent as notifications using the custom properties on the message. Type is String. If notification.queues is not specified, the Gateway logs a warning because the Gateway cannot subscribe to the designated notification queues and cannot receive any messages to deliver as a notification.
error.queue Optional If the Gateway fails to send a notification to Firebase for any reason, the reason for the error along with the message ID is logged. If an error queue is configured using error.queue, a message containing the details of the failure are published to the specified error queue.
badge.number.property.name Optional The name of the message property used to specify the badge number for the notification. Default is BADGE.
color.property.name Optional The name of the message property used to specify the color for the notification. Default is COLOR.
icon.property.name Optional The name of the message property used to specify the icon for the notification. Default is NOTIFICATION_ICON.
sound.property.name Optional The name of the property used to specify the sound for the notification. Default is NOTIFICATION_SOUND.
title.property.name Optional Indicates notification title. Type is String. Default is NOTIFICATION_TITLE.
Notes:
  • For details about the notification payload contents, see Firebase Cloud Messaging HTTP Protocol.
  • The names of the custom properties are configurable. You may specify your own property names but you must configure the Gateway with the custom property names using the JMS service configuration.
  • If the mandatory properties are not specified, the Gateway logs a warning. When the Gateway receives messages from the designated notification queue, they are not delivered as notifications. Instead, an exception is logged indicating the failure to send a notification and a message is published to error.queue, if configured.

Login Module for Secure Propagation of JMSXUserID Property

For security reasons, the Gateway sets the JMSXUserID property on the registration message instead of the Kaazing mobile client. The property is set using a LoginModule.

While applications write to the LoginContext Application Programming Interface (API), authentication technology providers implement the LoginModule interface. A Configuration specifies the LoginModule(s) to be used with a particular login application. The LoginContext is responsible for reading the Configuration and instantiating the specified LoginModules. Each LoginModule is initialized with a Subject, a CallbackHandler, shared LoginModule state, and LoginModule-specific options.

The Subject represents the user or service currently being authenticated and is updated by a LoginModule with relevant Principals and credentials if authentication succeeds.

To configure the LoginModule that will set the JMSXUserID, do the following:

  1. Review the steps for creating a LoginModule in Create a Custom Login Module.
  2. In your LoginModule, for example, com.example.NotificationsLoginModule populate the Subject with a known Principal with the user’s credentials, for example com.example.BpceNotificationsPrincipal.
  3. Implement a user identity resolver, for example com.example.NotificationsUserResolver, and add it to the JMS service configuration on the Gateway using the user.id.resolver property as shown below:
    <properties>
     <user.id.resolver>
      com.example.NotificationsUserResolver
     </user.id.resolver>
    </properties>
    

The NotificationsUserResolver can be implemented as shown below:

Public class NotificationsUserResolver implements Function<Subject, String> {

  public String apply(Subject subject) {
    Set<NotificationsPrincipal> principals = subject.getPrincipals(NotificationsPrincipal.class);

    if (principals != null && !principals.isEmpty()) {
      NotificationsPrincipal principal = principals.iterator().next();
      return principal.getName();
    }
    return null;
  }

For more information about configuring and implementing a user identity resolver, see Configure Auditing Messages Produced by Clients.

Prevent Client Subscriptions to Registration Queue

A registration queue used by Kaazing mobile clients to post messages that register their user IDs and Firebase device tokens with the backend service via the Gateway and JMS broker. While the backend service is subscribed to this queue, no clients should subscribe to it.

To prevent any client subscriptions to the registration queue, the customer can implement a JmsAuthorizationFactory such that the JmsAuthorization.canSubscribeToQueue() method returns false if the queue name passed in matches the name of the registration queue.

For an example of pluggable authorization, see Secure the Connection from Each Client to the Gateway and authorization.factory.

Error Queue

To notify the backend service of unsuccessful notifications, you can configure an error queue on the Gateway and JMS broker that the backend service can subscribe to. When the backend service receives messages from the error queue, it can determine what the best response is to perform.

To configure an error queue, use the error.queue element on the JMS service as follows:

<notifications>
...
<error.queue>NOTIFICATION_ERRORS</error.queue>
...
</notifications>

The name of the queue in this example is NOTIFICATION_ERRORS.

Before adding a message to the error queue, Gateway will set the following custom properties with appropriate values to help correct errors.

Property Name Type Description
NOTIFICATIONS_DEVICE_TOKEN String Required. Token of the device to where the notification was sent.
NOTIFICATIONS_REFRESHED_DEVICE_TOKEN String New or refreshed device token. This is set only when the value of the custom property NOTIFICATIONS_ERROR_CODE is DEVICE_TOKEN_REFRESHED.
NOTIFICATIONS_MESSAGE_ID String Required. Value of the JMSMessageID header.
NOTIFICATIONS_ERROR_CODE String Required. Check NOTIFICATIONS_ERROR_CODE Property Values for possible values of this property.
NOTIFICATIONS_ERROR_DESC String Required. Check NOTIFICATIONS_ERROR_CODE Property Values for values of this property corresponding to the error code.

NOTIFICATIONS_ERROR_CODE Property Values

NOTIFICATIONS_ERROR_CODE NOTIFICATIONS_ERROR_DESC
CONNECTION_DRAINING The message could not be processed because Firebase is draining. This happens because, periodically, the Firebase server needs to close down a connection to perform load balancing. Important: The backend service must republish messages that were not sent as notifications due to this issue.
CONNECTION_FAILED Failed to connect to Firebase.
DEVICE_MESSAGE_RATE_EXCEEDED The rate of messages to device with token \”%s\” is too high. Reduce the number of messages sent to this device, and do not immediately retry sending to this device.
DEVICE_TOKENS_PROPERTY_MISSING Missing required property \"%s\" on the notification message.
DEVICE_TOKEN_REFRESHED Warning from Firebase that the device token \"%s\" has been refreshed to \"%s\". Please use the refresh token from now on. The notification was still sent.
DEVICE_UNREGISTERED Device token \”%s\” may have ceased to be valid.
INVALID_DEVICE_TOKEN Device token \”%s\” is invalid.
INVALID_JSON Badly formatted JSON or size exceeded Firebase limits of 4K bytes.
INTERNAL_SERVER_ERROR Firebase server encountered an error while trying to process the request.
SERVICE_UNAVAILABLE Firebase server could not process the request in time.

Device Token Refresh

Firebase device tokens get refreshed periodically. The backend service must be able to manage refreshed tokens and update its user and device list. Here is an example of the process for token refresh:

  1. The Gateway sends a message to Firebase along with the device token token A.
  2. As part of the acknowledgement for that message, Firebase sends the newly refreshed token of the device (token B).
  3. This refresh information is then published as part of an error message that is sent by the Gateway to the configured JMS error queue.
  4. The backend service is subscribed to the error queue and receives the error message.
  5. The backend service must update the token from token A to token B.
  6. When the backend service publishes the next notification message to the notification queue, the custom property that provides the device token will include the refreshed token (token B).

Mobile App Configuration

The only Kaazing mobile client app configuration you need to perform is to set up your app for Firebase. Firebase must be added to your iOS and Android mobile clients to receive notifications from the Gateway. Once you have added Firebase, your app will use FCM to receive notifications.

For information on adding Firebase, see the following documentation from Firebase:

The mobile app must use the Kaazing JMS Client libraries to connect to Kaazing WebSocket Gateway.

Notes