kony.notificationsettings Namespace

The kony.notificationsettings namespace provides the following API elements.

Functions

The kony.notificationsettings namespace provides the following functions.

This API helps you create an action that can be used with category.

Syntax

kony.notificationsettings.createAction (actionId, label, pspConfig);

Input Parameters

Parameter Description
actionId [String] - Mandatory

Specifies a unique ID to identify the action chosen by a user.
label [String] - Mandatory Specifies a label that needs to be associated with a action.
pspConfig [JSObject] - Mandatory

Specifies the configuration function. The parameters follow:

  • image [Number] - Mandatory: This parameter is applicable only on the Android platform. Set the image to be displayed for notification settings.
  • activationMode [Number] - Mandatory: Specifies the activation mode. The options are:
    • kony.notificationsettings.ACTIVATION_MODE_FORWARDS: If you set this option, the action will occur in the foreground and launches the application interface.
    • kony.notificationsettings.ACTIVATION_MODE_BACKWARDS: If you set this option, the action will occur in the background without launching the application interface.

    NOTE: The activationMode property is applicable only for the iOS platform.

  • authenticationRequired [Boolean] - Mandatory: This parameter is applicable only on iOS platform. This parameter is applicable only when you set activationMode as kony.notificationsettings.ACTIVATION_MODE_BACKWARDS. The user needs to unlock the device, and action occurs in the background.
  • destructive [Boolean] - Mandatory: This parameter is applicable only on iOS platform. Set this value to true, if the notification is self destructive. Otherwise, set it to false.
  • visibleOn [String] - Mandatory: Set this parameter to display the notification on a watch, or both watch and phone. The options are:
    • kony.notificationsettings.WATCH_ONLY
    • kony.notificationsettings.BOTH

Example 


/*************************************************************************************
 * 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]
        }
    });

}

Return values

This API returns action as a JavaScript object.

Platform Availability

  • iOS
  • Android

This API helps you create a category with a group of created actions.

Syntax

kony.localnotifications.createCategory (categoryId, actions, pspConfig:{minimalActions:[actions] , presentationOptions});

Input Parameters

Parameter Description
categoryId [String] - Mandatory Specifies a unique ID for the group of actions that are defined.
actions [array] - Mandatory Specifies the actions that are associated with the category. Pass null, if no actions are associated with the category.

NOTE: In Default Context, you cannot add more than four actions on the iOS platform and three actions in the Android platform.

pspConfig [JSObject] - Mandatory Specifies the configuration function. The parameter is:
  • minimalActions [array] - Mandatory: This parameter is applicable only on the iOS platform. Specify the actions that are to be associated for minimal actions for the category.
  • presentationOptions [array] - You can use this parameter to configure the presentation options of notifications. This is a iOS-specific parameter. This parameter is available from V8 SP3 onwards.
    You can pass an array of the following values:
    • UNNotificationPresentationOptionBadge – 0: adds the notification badge icon.
    • UNNotificationPresentationOptionSound – 1: plays the sound.
    • UNNotificationPresentationOptionAlert – 2: displays the notification banner.

NOTE: In default mode, you cannot add more than two actions.

Example

Example 1:


var categoryObj = kony.notificationsettings.createCategory({
    "categoryId": "invitation",
    "actions": defaultActionContextArr,
    "pspConfig": {
        "minimalActions": minimalActionContextArr,
        "presentationOptions": [0, 1, 2]
    }
});

Example 2:


/*************************************************************************************
 * 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]
        }
    });

}

Return Values

This API returns category as a JavaScript object.

Remarks

  • If the presentationOptions parameter is not set, it is considered as no options are set and onlineNotification will not be shown.

  • Only the mentioned values of presentationOptions must be passed as array.

  • The input values for presentationOptions must consist of an array of minimum one value to a maximum of all three values. These options are applicable for all kinds of notifications.

  • Onclick of notification banner triggers the onlinenotification callback when the app is in foreground/active state, whereas the offlinenotification callback is triggered when the app is in background/inactive state.

Platform Availability

  • iOS
  • Android

This API helps you register the created category with the application.

Syntax

kony.notificationsettings.registerCategory (categories, pspConfig);

Input Parameters

Parameter Description
category [array] - Mandatory Specifies the category objects that are to be registered.
pspConfig [JSObject] - Optional This parameter is applicable on iOS platform only. It specifies the platform specific configuration function. The arguments are:
  • types [String] - Mandatory: Configure this parameter to register the type of notification. The Array for iPhone must contain any or all of the following:
    • 0 - Specifies the notification type as Badge.
    • 1 - Specifies the notification type as Sound.
    • 2 - Specifies the notification type as Alert.

NOTE: If the types are not passed or pspConfig is not defined, then all the notification types are registered by the API.

NOTE: If the same API is invoked multiple times, the details of the last invoked call are updated.

Example 


/*************************************************************************************
 * 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]
        }
    });

}

Return Values

None

Remarks

Handling Local and Remote Notifications Callbacks:

  • If the app is in the foreground state (app instance alive), an onlinecallback should be invoked.
  • If the app is in background state (app instance alive or not alive), an offlinecallback should be invoked.

Platform Availability

Available on the iOS and Android platforms.

Once you set the kony.notificationsettings.pickTitleAndDescriptionFromPushPayload API as true, the Title and Description details of the payload are considered. By default, the Title and Description information of the payload are not respected.

Syntax

kony.notificationsettings.pickTitleAndDescriptionFromPushPayload (pickTitleAndDescriptionFromPushPayloadKey);

Input Parameters

Parameter Description
pickTitleAndDescriptionFromPushPayloadKey [Boolean] - Mandatory Set this input parameter as true to ensure that the Title and Description data of the payload are taken into consideration.
 

Example


var pickTitleAndDescriptionFromPushPayloadKey = true;
kony.notificationsettings.pickTitleAndDescriptionFromPushPayload (pickTitleAndDescriptionFromPushPayloadKey);

Remarks

  • The Boolean value that is passed in the pickTitleAndDescriptionFromPushPayloadKey input parameter is stored in Shared Preferences.

Platform Availability

  • Android

You can use the kony.notificationsettings.setProperties API to set various properties of notifications that belong to a category.

Syntax

kony.notificationsettings.setProperties(categoryId, properties);

Input Parameters

Parameter Description
categoryId The category ID of the notification for which the priority is set. The value type of categoryId is String.
properties

The configuration object of the category. The value type of properties is JSON object.

Currently, the JSON object contains the priority key.

priority: A property for setting priority to the notification object related to a category. The value type of priority is constant.

The priority key contains one of the following constants:

  • constants.NOTIFICATION_PRIORITY_DEFAULT: Default notification priority.

  • constants.NOTIFICATION_PRIORITY_HIGH: Higher notification priority is set for important notifications.

  • constants.NOTIFICATION_PRIORITY_LOW: Lower notification priority is set for notifications that are less important.

  • constants.NOTIFICATION_PRIORITY_MAX: Highest notification priority is set for an app's most important items that require the end user's prompt inputs.

  • constants.NOTIFICATION_PRIORITY_MIN: Lower notification priority is set for items that are less important. You can choose to display these items in a smaller size, or at a different position in the list compared to the app's PRIORITY_DEFAULT items.

Example 


propTable = {};
propTable.priority = constants.NOTIFICATION_PRIORITY_HIGH;
kony.notificationsettings.setProperties({
    categoryId: "invitation",
    properties: propTable
});

Platform Availability

  • Android

This API helps you to enable or disable notification badges for push/remote or local notifications that are only supported by Quantum Visualizer Framework. By default, the visibility of the notification badge is set to true on Android 8.0 devices.

Syntax

kony.notificationsettings.setShowBadge(notificationChannelName, showBadgeValue);

Input Paramters

Parameter Description
notificationChannelName [String] - Mandatory The following values are applicable for this parameter:

  • "localNotification"

  • "pushNotification"
showBadgeValue [Boolean] - Mandatory Set this value to false to disable the visibilty of the app notification badge.
 

Example


var notificationChannelName = "pushNotification";
var showBadgeValue = false;
kony.notificationsettings.setShowBadge(notificationChannelName, showBadgeValue);

Remarks

  • You must call this API in preapp init, as the badge visibility can only be set after the first notification is received. This is because the channel creation is done after the first notification is initiated; once the channel creation is done, the visibility of the notification badge cannot be modified.
  • Some launchers may not support the Notification Badge feature, even on devices with Android 8.0 and later.

Platform Availability

  • Android 8.0 and later