Skip to end of metadata
Go to start of metadata

Introduction

You can create interactive notifications, where users can respond to application notifications without launching the application to the foreground. The user needs to reveal notification actions in the notification, then press a notification action to respond to the notification. This feature is available on devices running iOS 8 or later.

To create an interactive notification, the applications needs to:

  1. Create and configure notification actions
  2. Create notification categories and assign notification actions to them
  3. Register the notification categories
  4. Monitor the localnotificationaction event to respond to local notifications and the remotenotificationaction event to respond to push notifications

Interactive notification types

The following screenshots illustrate how iOS presents and the user interacts with the notification:

Alert dialog

The user needs to tap the Options button when the alert dialog first appears to display the notification actions. Tapping Open launches the application in the foreground, while tapping Close dismisses the notification.

Banner message

In a banner message, the user needs to swipe the banner message down to reveal the notification actions. Tapping the notification (not an action) launches the application in the foreground. The user can dismiss the notification by swiping up the notification tray.

Lock screen or notification center

In the lock screen or notification center, the user needs to swipe the notification to the left to reveal the notification actions. If the user swipes the notification to the right in the locked screen, the application is launched in the foreground. The user can dismiss the notification by tapping the button.

Create a notification action

A notification action is an action that the application performs in response to a notification. The action is represented as a button in the notification.

To create a notification action, use the Titanium.App.iOS.createUserNotificationAction() method. Pass the method a dictionary with the following required properties:

  • activationMode:
    • Set to Titanium.App.iOS.USER_NOTIFICATION_ACTIVATION_MODE_BACKGROUND to activate the application in the background to respond to the action unless the application is already in the foreground.
    • Set to Titanium.App.iOS.USER_NOTIFICATION_ACTIVATION_MODE_FOREGROUND to launch the application in the foreground to respond to the action.
  • authenticationRequired: set to true if the action requires the device to be unlocked.
  • destructive: set to true if the action causes destructive behavior to the user's data or the application. The action appears red in the locked screen and notification center instead of the default color.
  • identifier: string identifier of the action. Used to identify the action the user pressed.
  • title: title of the button to display in the notification

Create a notification category

A notification category is a group of notification actions for a specific notification. The notification category allows the application to customize the notification options based on which notification style is used. For alert dialogs, only four notification actions can be displayed, while all other notifications can only display two actions.

To create a notification action, use the Titanium.App.iOS.createUserNotificationCategory() method. Pass the method a dictionary with the following properties:

  • actionsForDefaultContext: Array of notification action objects to associate with the group. Note that only the first four actions can be displayed for an alert dialog and the first two actions can be displayed for all other notifications.
  • actionsForMinimalContext: Array of notification action objects to display for non-dialog-style notifications. If not specified, the first two actions from actionsForDefaultContent are displayed.
  • identifier: string identifier of the group of actions. When scheduling a notification, pass this value to the category property.

Register notification categories

Like notification types, you also need to register notification categories with iOS by using the  Titanium.App.iOS.registerUserNotificationSettings() method. Pass the method a dictionary with the type property set to the notification types to use and the categories property to an array of notification category objects the application needs to use.

If you are using push notifications, the application needs to call the Titanium.Network.registerForPushNotifications() method. The application should monitor the usernotificationsettings to register for push notifications. 

Monitor interactive notifications

The application can monitor interactive notifications and respond to them in the background by using the  iOS application-level localnotificationaction event for local notifications and remotenotificationaction event for push notifications. The event is triggered when the user selects a notification action.

localnotificationaction

Monitor the iOS application-level localnotificationaction event to respond to an interactive local notification.  The event is passed the same object as the  notification  event except it returns two extra properties:

  • category: string identifier indicating the notification category that triggered the event
  • identifier : string identifier indicating the notification action the user pressed
Use the properties to have the application decide how to respond to the interactive notification.

 

remotenotificationaction

Monitor the iOS application-level remotenotificationaction event to respond to an interactive push notification. The event is passed an object with the following  properties:

  • category: string identifier indicating the notification category that triggered the event
  • data: push notification payload as a JSON object
  • identifier: string identifier indicating the notification action the user pressed
Use the properties to have the application decide how to respond to the interactive notification.

Schedule an interactive local notification

To send an interactive local notification, use the Titanium.App.iOS.scheduleLocalNotification() method. Use it the same way when scheduling a non-interactive local notifications except when creating the dictionary of options to pass to the method, the application must specify the category property and set it to the identifier of the notification category to use.  The notification category indicates which group of actions to use with the notification.  The notification category must also be registered or else the notification will be presented as a default non-interactive notification.

Send an interactive push notification

To send an interactive push notification, send a payload with the category field set to the identifier of the notification category to use.

To send the payload, you can use either the:

Example

In the following example, run the code on an iOS device or simulator. Click the "Trigger Notification" button, then either lock the phone or place the application in the background.  You will have three seconds or else the application will respond to the notification in the foreground. If the device or simulator is running iOS 8 or later, you will receive the interactive local notification. If not, you will receive a regular local notification.

  • No labels