Customizing GCM Broadcast Receiver
Volt MX Iris for Android development allows you to customize the native Google Cloud Messaging (GCM) receiver and push message status notification to meet your application requirement. Otherwise, the default settings of Volt MX Iris take effect.
GCM Overview
An Android application developed in Volt MX Iris shows the status bar notification for new push message if the application is in background, whether running or not running. The default GCM notification message is shown below:
-
The notification provides an icon and two-line text for title and description of the message. The notification message appears below:
- A push message is composed of key value pairs. A random key is picked from a payload, and its corresponding value is shown as both title and description of a notification.
- By default, only one notification is displayed per application on the status bar. Any new push message received will overwrite the existing notification.
Integrating pushconfig.xml
The pushconfig.xml
file is pre-bundled in the Android application structure in Volt MX Iris. This pushconfig.xml
file is available once the application is built in Volt MX Iris.
To locate and integrate the pushconfig.xml
into the application, do the following:
- Build your application for the Android platform. Once the build is complete, the Build Generation Status dialog appears.
- Click OK. The dialog closes.
- Open the build folder. To open the build folder, press Ctrl + Alt + T, or click the Open Resource location drop-down and select Open Build Folder.
- Navigate to
build\luaandroid\dist\<App_Name>\res\values
. - Select and copy the
pushconfig.xml
file. - Click Open Resource location drop-down and select Open Resource location.
-
Paste the file in the following location:
resources/mobile/native/android/values
(create this folder structure if it does not exist). - Open the
pushconfig.xml
and modify values to override the default behavior.
The following table describes the icon names used in this topic:
Icon | Name |
---|---|
Open Resource Location icon |
You can modify or customize GCM in two ways:
- By modifying pushconfig.xml file - Used for modifying only a defined set of options.
- By modifying KonyGCMBroadcastReceiver class - Used for modifying the way messages appear and other advance options.
Modifying pushconfig.xml File
The default behavior of the GCM 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.
The registration allows the application to receive the registration ID. The intent can be sent at any time. Google may periodically refresh the receiver ID. An application receiving this intent with a registration_id parameter must ensure that the third-party application server (for example, VPNS) receives the registration ID. The application may do so by saving the registration ID and sending it to the server. If the network is down or there are errors, the application should resend the registration ID when the network is up again or the next time it starts. An application should keep track of its registration status and attempt to register again if the process is not completed. If the new registration ID arrives while the app is not running, a notification appears on the status bar.
Important: Android GCM documentation does not have enough information on what are the circumstances to refresh the registration ID and its frequency of occurrence.
A couple of keys in pushconfig.xml
are provided to customize the notification.
The table below shows a list of key value pairs, each with a brief description.
Notification ID | Default Value | Description |
---|---|---|
notify_new_regid | true | Enable or disable new registration ID notifications. If disabled, new registration IDs are not issued to the application when it is offline. |
notify_new_regid_icon | icon (.png file) | Specify icon resource without extension. For example, logo for logo.png. The default is icon.png |
notify_new_regid_title | ID | Text to show for new registration ID notification as title. Since a new registration ID event does not contain any payload, an application can show some meaningful text to the user. |
notify_new_regid_desc | Text displays new registration ID notification. | |
notify_new_regid_sound | false | Enable or disable sound for new registration ID notification. |
notify_new_regid_vibrate | false | Enable or disable vibrate for new registration ID notification. |
notify_new_regid_lights | false | Provides option to clear unread new registration ID notification. |
notify_push_msg | true | Enable or disable new push message notifications. If false, no status bar notification is shown when application is running in background. |
notify_push_msg_notifications_count | 1 | By default, only latest push message notification is kept in the status bar. Use this option to control the number of messages to be stored. The maximum limit allowed in Android is 50. > Note: After exceeding the storage limit, older messages are replaced with newer messages. However, sometimes older notifications are replaced with newer messages even before it reaches the specified count (this happens when the app is closed by Android system) |
notify_push_msg_icon | icon | Specify icon resource without extension. For example, logo for logo.png. The default is icon.png. |
notify_push_msg_default_title | new push message | Title is used for new push message notifications if “title_from_payload” is set to false. |
notify_push_msg_title_from_payload | true | Indicates whether to pick notification title from the push message. If true, notify_push_msg_title_keys is used to pick the notification title. |
notify_push_msg_title_keys | Key to be used to pick the notification title. Keys separated by a comma (,) can be provided, and the first available key in a payload is used as a notification title. | |
notify_push_msg_default_desc | Used to provide new push message notifications description only when desc_from_payload is set to false. | |
notify_push_msg_desc_from_payload | true | Indicates whether to pick notification description from push message. if true, notify_push_msg_desc_keys is used to pick the notification description. |
notify_push_msg_desc_keys | Used to pick the notification description. Keys separated by a comma (,) can be provided, and the first available key in a payload is used as a notification description. | |
notify_push_msg_sound | true | Enable or disable sound for push message notification. |
notify_push_msg_vibrate | true | Enable or disable vibrate for push message notification. |
notify_push_msg_lights | true | Enable or disable lights for push message notification. |
notify_push_msg_clear | true | Indicates that the user must take action to clear the push message notification. Setting the value to false clears the push message notification without user intervention. |
Modifying KonyGCMBroadcastReceiver Class
If you need to customize GCM apart from what is provided in the pushconfig.xml
file, you can replace the platform default GCM broadcast receiver with the custom GCM broadcast receiver. The custom GCM receiver inherits from the default Volt MX GCM broadcast receiver KonyGCMBroadcastReceiver class that is available in voltmxwidgets.jar
. Provide a fully qualified class name in Volt MX Iris by going to Properties->NativeApp->Android->Push Notification
.
Customizing the KonyGCMBroadcastReceiver class allows you to:
- Create a multiline notification in the status bar.
- Know the arrival of a push message immediately even when the application is in the background.
- Handle an offline push messages when the application is in the background.
Here is the API for the default GCM broadcast receiver along with comments:
GCM Custom Implementation Example
For more information on GCM notifications, see http://developer.android.com/guide/topics/ui/notifiers/notifications.html.
Notification in collapsed mode (normal):
Notification in expanded mode (big view mode):
You can use the following sample code and tweak as required: