Push Notifications

Push Notifications is a mechanism using which you can initiate a message delivery to a device without receiving a request. Push notifications are sent by Quantum Fabric Engagement Services to the Apple Push Notification Service (APNS), which pushes the notification to devices.

NOTE: Push Notifications will not work in the simulator.

The Notification Payload For Push Notification

Each push notification includes a payload In iOS 8 and later, the maximum size allowed for a notification payload is 2 kilobytes. Apple Push Notification service refuses any notification that exceeds this limit. (Prior to iOS 8, the maximum payload size is 256 bytes.)

NOTE: Delivery of notifications is a “best effort”, not guaranteed. It is not intended to deliver data to your app.

When you run your app on a device with Android OS 8.0 or above, Kony uses default channels that are mentioned in the pushconfig.xml file.

For a more hands-on approach in the understanding and implementation of Push Notifications API, you can import and preview the Events app by using Quantum Visualizer.

How it Works

The following are the primary processes involved in an application being setup for Push Notifications:

  1. Enabling Push Notifications: When an application needs to use the Push Notifications service, it uses the kony.push.setCallbacks function and specifies the functions to be executed for Push Notifications.
    The application then uses the kony.push.register API to register the application and the device with the corresponding Push Notification Service provider of the device OS.
  2. Sending Push Notifications: If the registration is successful, the application can receive Push Notifications on the device from the third-party application server.
  3. Receiving a Message: The third-party application server sends a Push Notification to the application and the device extracts the data from the message and passes it to the application.
  4. Disabling Push Notifications: The application can deregister from Push Notification service by using the kony.push.deRegister function.

Platforms Supporting Push Notifications

Push Notifications are currently supported only by Android and iPhone platforms.

For Push Notifications to work, the application and the device must first register with the corresponding Push Notification Service provider of the device os.

The following is the list of platforms and their corresponding Push Notifications Service providers they must register with:

Platform Push Notifications Service
Android/Android Tablet

Google Cloud Messaging (GCM)

Deprecated:Android Cloud to Device Messaging (C2DM)

iPhone Apple Push Notification Service (APNS)
Desktop Web Google Firebase Cloud Messaging (FCM)

Enabling Push Notifications

To enable Push Notifications for an application do the following:

  1. The application uses the kony.push.setCallbacks function and specifies the functions to be executed for Push Notifications.
  2. The application uses the kony.push.register API to register for Push Notifications with the corresponding Push Notification Service provider of the device OS.
  3. If the registration is successful, the Push Notification Service provider returns a unique identifier to the device.

    The following is the list of Push Notification Service providers and the unique identifier they return:

    4. Push Notifications Service Returned Unique Identifier

    Google Cloud Messaging(GCM)

    Deprecated: Android Cloud to Device Messaging (C2DM)

    Firebase Cloud Messaging (FCM)

    		 Registration ID
    Apple Push Notification Service (APNS) DeviceToken
    Microsoft Push Notification Service (MPNS) Unique URL
  1. The application sends the identifier to the third-party application server. The third-party application server can use this identifier to send Push Notifications to it.

    2. The following image illustrates the steps involved in enabling Push Notifications for an application on a device:

Sending Push Notifications

The following are the steps involved in a third-party application server sending Push Notifications to an application on a device:

  1. The third-party application server uses the unique identifier (sent by the application ) in sending the Push Notifications to the Push Notification Service provider of the device.
  2. The Push Notification Service provider then sends the Push Notification message to the application on the device.

    3. The following image illustrates the steps involved in sending Push Notifications to an application on a device:

Receiving a Message

When an application on a device receives a message, the following sequence of events occur:

  1. The device receives the incoming Push Notification and extracts the data from the message payload.
  2. The device passes the data to the application.
  3. The application processes the data and displays it to the user.

Disabling Push Notifications

You can use the kony.push.deRegister API and deregister the application and the device from the Push Notifications service.

Silent Push Notifications

Push notifications can occur in the background without triggering a notification that is visible to the app's user through its UI. These are known as silent notifications and are often used to download data in the background while the user continues with other tasks.

To enable your app to receive silent notifications, your app must call the kony.push.setCallbacks function and pass it the onlinenotification callback function that is invoked whenever a silent notification arrives from a Quantum Fabric server. The onlinenotification function then checks the payload from the server to see if it has received a silent notification. The payload has the following format.

            
{
    "data": {
        "mid": "8304002566299090338",
        "content-available": “1”
    }
}

Note in particular that the data contains the key "content-available", which is set to "1". This specifies to your app that a silent notification has been received and that it should process the notification silently. Therefore, it should not display UI alerts to the user or put itself into foreground mode if it is running in the background. Instead, the callback function your app sets through the onlinenotification parameter of the kony.localnotifications.setCallbacks function is invoked automatically so that it can process the notification without disturbing the user. The callback function is invoked irrespective of the current state of the app. So the app can be running, not running, in the foreground, or in the background and still receive the silent notification.

To enable silent push notifications, your app must be able to receive push messages from the server. It must also call the kony.localnotifications.setCallbacks function when processing either the pre-appinit or post-appinit events.

 

API Functions for Push Notifications

Quantum Visualizer platform provides APIs that you can use to enable Push Notifications for an application on a device and also an API to deregister from the Push Notifications service.

The following are the APIs for Push Notifications:

  1. kony.push.setCallbacks
  2. kony.push.register
  3. kony.push.deRegister

    4. NOTE: The following are the generic error codes for Push Notification APIs:

Error Code Error Message
1400 Invalid number of arguments.
1401 Illegal arguments.
1402 Unable to connect to push service - PNS service is not available
1406 Platform-specific issue. Full details are available in the errormessage. For example, received payload but payload is in incorrect format.

IMPORTANT: Use Error Codes to refer and do not rely on Error Messages as each message may differ from platform to platform.

Important Considerations for Android

The following are the important considerations you must be aware for Android platform:

  • Before you build the application for Android, navigate to the Project Properties of the application and navigate to Native App -> Android tab, and select the GCM under the Push Notification section. Selecting this option will copy the required Push Notification libraries into the application during build time."

  • For C2DM to GCM conversion refer, http://developer.android.com/guide/google/gcm/c2dm.html

  • Google may occasionally refresh the Registration ID. Hence, you must design the application to update the third-party Application server with the new ID.



    If the Quantum Android platform receives a new registration ID, the following takes place:

    • If the application is running in the foreground or the background - onsuccessfulregistration function is called.
    • If the application is not running - a status bar notification is displayed. If you select the notification, the application is launched and onsuccessfulregistration function is called.
  • If the Quantum Android platform receives a new Push notification message, the following takes place:
    • If the application is running in the foreground:
      • GCM - Online callback is triggered without any notification.
      • FCM - Online callback is triggered without any notification.
    • If the application is running in the background:
      • GCM - A status bar notification is displayed. If you click the notification, the application is brought to the foreground and its onlinenotification function is called.
      • FCM - A status bar notification is displayed. If you click the notification, the application is brought to the foreground and its onlinenotification function is called.
    • If the application is not running:
      • GCM - A status bar notification is displayed. If you click the notification, the application is launched and its offlinenotification function is called.
      • FCM - Any of the following can occur:
        • If the payload contains a notification key (for example, when the 'Enable GCM v3.0 Payload for Android' check box is selected in KMS console), a status bar notification is displayed by the system. If you click the notification, the application is launched and its onlinenotification function is called.
        • If the payload does not contain a notification key (for example, when the 'Enable GCM v3.0 Payload for Android' check box is not selected in KMS console), a status bar notification is displayed by Framework. If you click the notification, the application is launched and its offlinenotification function is called.
  • The status bar notification is displayed by the platform with the default settings.
    The default settings are in the pushconfig.xml file (available after the application is built) in the 'dist{APP-ID}\res\values' location. You can modify these settings by using a regular expression replacement task that is written in the androidprecompiletask.xml file.
    For example, if you want to update the value of the 'notify_push_msg_title_keys' key to 'title,' you must use the following code snippet, which replaces the value
    directly in the file.

    <replace file="${app.dir} /res/values/pushconfig.xml"

    token="<string name="notify_push_msg_title_keys">"

    value="<string name="notify_push_msg_title_keys">title"/>


    Similarly, you can configure other keys by using the androidprecompiletask.xml file.
  • To customize GCM broadcast receiver, refer Quantum VisualizerUser Guide.

NOTE: From the Quantum Visualizer 202306 release, if the Target SDK API level of the app is set as 33, and the app uses the Push Notifications APIs, you must enable support for runtime permissions for notifications.
To do so, navigate to Project Settings > Native > Android Mobile / Tablet, and add the POST_NOTIFICATION permission in the Permissions tab.

Important Considerations for Desktop Web

  • From Project Settings of your Visualizer project, you must go to the Desktop Web tab and perform the following actions:

    • Select the Enable PWA checkbox.
    • Select the Enable push notifications check box.
    • Specify your messagingSenderId in the FCM Sender ID field.
  • Push notifications will work only when you build the app in Release mode.

  • Push notifications work only in HTTPS environment, which means that you must publish the app in HTTPS server.

    IMPORTANT: Desktop web push notifications are not supported on localhost.

  • The Push notifications feature for the Desktop Web channel is supported from V8 SP4 onwards.

  • Push notifications for the Desktop Web channel is not supported in:

    • Mac Safari
    • All web browsers in iOS

  • If a web browser has the support for service worker, only then push notifications will work in that browser.

  • If the Quantum Desktop Web platform receives a new Push notification message, the following takes place:

    • If the application is running in the foreground, an online callback is triggered without any notification.

    • If the application is running in the background or if the application is not running, a status bar notification is displayed.

Modifying pushconfig.xml File in Android Platform

The default behavior of the push notification message can be customized by modifying the pushconfig.xml file. The pushconfig.xml file contains key value pairs that allow applications to configure individual keys to override the default behavior.

You can customize the notification using the keys provided in pushconfig.xml.

The table below shows a list of key value pairs, each with a brief description.

Notification ID Default Value Description
notify_push_msg_channel_title Push Notifications Channel title for push notifications.
notify_push_msg_channel_desc All push notifications will be displayed under this category Channel description for push notifications.
use_same_channel_details_for_local_notifications false If configured to true, same channel details will be used for local notifications.

You can get detailed information regarding the implementation of Push Notifications on various platforms, by visiting the following links: