Local Notifications

Local notifications are scheduled by an app and delivered on the same device. They are suited for apps with time-based behaviors, such as calendar events.

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

NOTE: Each app on a device is limited to 64 scheduled local notifications. The system discards scheduled notifications exceeding this limit. Recurring notifications are treated as a single notification.

The local notification system consists of the following namespace and related functions:

Initializing Local Notifications

To initialize your app to receive local notifications, it must invoke the kony.localnotifications.setCallbacks function in the Notifications API and pass it the callback handler functions. The following sample code demonstrates how to initialize local notifications.

/*************************************************************************************
 * Function:localNotCallBacks()
 * Description: Initializes local notifications.
 * Author: Kony
 *************************************************************************************/
function localNotCallBacks() {
    try {
        kony.localnotifications.setCallbacks({
            "offlinenotification": offlinenotification,
            "onlinenotification": onlinenotification
        });
    } catch (err) {
        kony.print("Error Code " + err.errorCode + " Message " + err.message);
    }
}

/* Notification callback handlers. These are invoked automatically when their respective notifications are fired. */
function offlinenotification(notificationobject, actionid) {
    alert("offline notification callback inkvoked");
    alert("notification object is :" + JSON.stringify(notificationobject) + " action id is " + actionid);
}

function onlinenotification(notificationobject, actionid) {
    alert("onlinenotification notification callback inkvoked");
    alert("notification object is :" + JSON.stringify(notificationobject) + " action id is " + actionid);
}

 

Creating Local Notifications

Your app creates local notifications that are triggered then their corresponding events occur.

/*************************************************************************************
 * Function:createLocalnotification()
 * Description: Creates local notifications.
 * Author: Kony
 *************************************************************************************/
function createLocalnotification() {
    var notificationId = "01";
    var date = "05 jan 2017 16:42:00 +0530";
    var format = "dd MMM yyyy HH:mm:ss Z";
    var message = "Local notification Received";
    var title = "Title";
    var categoryId = "calendar";

    kony.localnotifications.create({
        "id": notificationId,
        "dateTime": {
            "date": date,
            "format": format
        },
        "message": message,
        "title": title,
        "categoryId": categoryId,
        "pspConfig": {
            "badge": 1,
            "sound": kony.localnotifications.DEFAULT_SOUND
        }

    });

}

NOTE: The local notification API, kony.localnotification.create

       •   Can be called directly in Android devices.

       •   In iOS devices you must first call kony.notificationsettings.registerCategory API in order to call the create API.

Canceling Local Notifications

To stop receiving local notifications, your all calls the kony.localnotifications.cancel function, as shown in the code sample below.

/*************************************************************************************
 * Function:cancelLocalnotifications()
 * Description: Cancels local notifications.
 * Author: Kony
 *************************************************************************************/
function cancelLocalnotifications() {
    notificationIdArray = [];
    notificationIdArray.push("01");
    kony.localnotifications.cancel(notificationIdArray);
}

Creating Actions and Categories

Your app can create categories of notifications and set actions for those categories. To do so, it call the kony.notificationsettings.registerCategory function, as illustrated in the following sample code.

/*************************************************************************************
 * Function:registerActions()
 * Description: Creates Actions and a Category.
 * Author: Kony
 *************************************************************************************/
function registerActions() {
    var accept = kony.notificationsettings.createAction({
        "id": "Accept",
        "label": "Accept",
        "pspConfig": {
            "authenticationRequired": true,
            "destructive": true,
            "activationMode": kony.notificationsettings.ACTIVATION_MODE_FORWARDS,
            "visibleOn": kony.notificationsettings.BOTH
        }
    });

    var reject = kony.notificationsettings.createAction({
        "id": "Reject",
        "label": "Reject",
        "pspConfig": {
            "authenticationRequired": false,
            "destructive": false,
            "activationMode": kony.notificationsettings.ACTIVATION_MODE_FORWARDS,
            "visibleOn": kony.notificationsettings.BOTH
        }
    });

    var decline = kony.notificationsettings.createAction({
        "id": "Decline",
        "label": "Decline",
        "pspConfig": {
            "activationMode": kony.notificationsettings.ACTIVATION_MODE_BACKWARDS,
            "authenticationRequired": true,
            "destructive": false,
            "visibleOn": kony.notificationsettings.BOTH
        }
    });


    var defaultActionContextArr = [accept, reject, decline];
    var minimalActionContextArr = [accept, reject];

    var categoryObj = kony.notificationsettings.createCategory({
        "categoryId": "invitation",
        "actions": defaultActionContextArr,
        "pspConfig": {
            "minimalActions": minimalActionContextArr
        }
    });


    //Using kony.notificationsettings.registerCategory 

    var categoryArr = [categoryObj];

    var registerCategory = kony.notificationsettings.registerCategory({
        "categories": categoryArr,
        "pspConfig": {
            "types": [0, 1, 2]
        }
    });

}

Important Considerations for Android Platform

  • The default settings are located in the localnotificationconfig.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_local_msg_notifications_count' key from '1' to '5 ', you must use the following code snippet, which replaces the value directly in the file.

    <replace file="$
{app.dir}/res/values/localnotificationconfig.xml" 
token = "<string name="notify_local_msg_notifications_count">1" 
value = "<string name="notify_local_msg_notifications_count">5"/>

    Similarly, you can configure other keys by using the androidprecompiletask.xml file.

  • From the Quantum Visualizer 202306 release, if the Target SDK API level of the app is set as 33, and the app uses the Local 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.

Modifying localnotificationconfig.xml File in Android Platform

The default behavior of the local notification message can be customized by modifying the localnotificationconfig.xml file. The localnotificationconfig.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 localnotificationconfig.xml.

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

Notification ID Default Value Description
notify_local_msg true Enable or disable new local message notifications. If false, no status bar notification is shown when application is running in background.
notify_local_msg_channel_title Local Notifications Channel title for local notifications.
notify_local_msg_channel_desc All local notifications will be displayed under this category Channel description for local notifications.
notify_local_msg_notifications_count 1

By default, only the latest local 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 the storage reaches the specified count (this happens when the app is closed by the Android system).
notify_local_msg_icon icon Specify icon resource without extension. For example, set a logo to use an image for the message icon for which the file name is logo.png. The default is icon.png.
notify_local_msg_sound true Enable or disable sound for local message notification.
notify_local_msg_vibrate true Enable or disable vibrate for local message notification.
notify_local_msg_lights true Enable or disable lights for local message notification.
notify_local_msg_clear true Indicates if a user can clear the unread local message notification.