- Notification Types
- Configure Notification Settings
- Send a Local Notification
- Create an Interactive Notification
Local notifications alert the user that something is happening to your application while it is in the background. On iOS, the notification can appear as an alert or banner message and stays in the notification center until the user clears them. The user can tap or swipe the notification to launch the application or dismiss the notification. The application can also play a sound or modify its badge value on its icon. Note that the user can customize how they want to receive notifications from Settings. They can change how the message appears or even disable them.
Starting with Release 3.4.0, the application can create interactive notifications if the device is running iOS 8 or later. An interactive notification presents options that the user can tap to respond to the application while it is in the background.
The following sections describe how iOS may present notifications to users.
If the application is in the background and the device is unlocked, iOS presents the notification as either a banner message or an alert depending on the user's selection. The user can tap on Open to launch the application, while tapping Close dismisses the notification.
The application can optionally set the badge value, which appears in the application's icon. Use the value to indicate the number of items the user needs to respond to. After the user responds, be sure to reset the badge value.
If the application is in the background and the device is unlocked, iOS presents the notification as either a banner message or an alert depending on the user's selection. The user can tap the banner message to launch the application. If the user does nothing, the banner message eventually disappears and the notification will be queued in the notification center.
If the device is locked, the notification appears in the lock screen. The user swipes the notification to the right to launch the application.
If the user never responds to notifications, the notifications are queued in the notification center. The user can click on the notification to launch the application or click the x button to clear the notifications.
The application can play a sound when a notification is received.
Configure Notification Settings
The user can configure how to receive notifications from your application using Settings. To access the notification settings, open Settings, then:
- For iOS 8 and later, tap the application to configure, then tap Notifications.
- For iOS 7, tap Notification Center, then tap the application to configure.
In the Notifications screen, the user can selectively decide which notification types to receive.
Send a Local Notification
To send a local notification, use the
Titanium.App.iOS.scheduleLocalNotification() method. The application can monitor local notifications using the
notification event. For devices running iOS 8 and later, you need to register the application to use the local notification service before scheduling local notifications.
Register for Local Notifications
For devices running iOS 8 and later, you need to register the application to use the local notification services. Use the
Titanium.App.iOS.registerForLocalNotifications() method to enroll the application in local notification services. Pass the method a dictionary with the
type property set to the notification types to use. You can bitwise-OR the following constant values:
Titanium.App.iOS.NOTIFICATION_TYPE_ALERT: allow the application to display an alert or banner message.
Titanium.App.iOS.NOTIFICATION_TYPE_BADGE: allow the application to modify the badge value in the application's icon.
Titanium.App.iOS.NOTIFICATION_TYPE_NONE: disable application UI notifications. The application will still be notified of the notification by the
Titanium.App.iOS.NOTIFICATION_TYPE_SOUND: allow the application to play a sound.
After the application registers for notification services, iOS will prompt the user to allow the application to send notifications or not. The user can reconfigure the notification settings later from Settings.
Schedule a Local Notification
To send a local notification, use the
Titanium.App.iOS.scheduleLocalNotification() method. Pass the method a dictionary with the following properties. All properties are optional:
alertAction: modify the default slider text of the alert ("slide to view") (see diagram below) or the title of the Open button for the alert dialog. The value replaces "view" for the slide text, so the message will be "slide to <alertAction>".
alertBody: text to display in the alert or banner message (see diagram below). If omitted, an alert is not displayed.
alertLaunchImage: splash image to display instead of the application's default splash image.
badge: number to set in the application icon's badge. To remove the badge value, set the value to a negative number.
category: string identifier of the category of actions to be displayed in the interactive notification (for iOS 8 and later).
repeat: interval to repeat the notification. Values can be:
yearly. Default is once.
sound: sound file to play relative to the
timezone: timezone of the date configured for the notification. If not set, the system timezone is used.
userInfo: extra data to pass to the application that can be processed in the
scheduleLocalNotification() method returns a LocalNotification object. The application can use the object to call the
cancel() method in case it needs to cancel the notification.
Monitor Local Notifications
The application can monitor incoming local notifications by using the iOS application-level
notification event if it is in the foreground or returns to the foreground. The event is passed a dictionary containing the same properties as the ones used to schedule the notification except the
Cancel a Notification
If the application needs to cancel a notification, it can either selectively choose which notification(s) to cancel or cancel all pending notification.
To cancel all pending notifications, call the
To cancel a specific notification, the application can either:
- Keep a reference to the notification object and call the
cancel()method on the object.
- Add an ID to the notification and pass the ID to the
Titanium.App.iOS.cancelLocalNotification()method. To add an ID to the notification, set the
idproperty of the
userInfodictionary passed to the
Create an Interactive Notification
Starting with Release 3.4.0, 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:
- Create and configure notification actions
- Create notification categories and assign notification actions to them
- Register the notification categories
- Monitor the
backgroundNotificationevent while the app is the background
The following screen shots illustrate how iOS presents and the user interacts with the notification:
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.
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 x 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:
- Set to
Titanium.App.iOS.NOTIFICATION_ACTIVATION_MODE_BACKGROUNDto activate the application in the background to respond to the action unless the application is already in the foreground.
- Set to
Titanium.App.iOS.NOTIFICATION_ACTIVATION_MODE_FOREGROUNDto launch the application in the foreground to respond to the action.
- Set to
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
identifier: string identifier of the group of actions. When scheduling a notification, pass this value to the
Register Notification Categories
Like notification types, you also need to register notification categories with iOS by using the
Titanium.App.iOS.registerForLocalNotifications() 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.
Monitor Interactive Notifications
The application can monitor interactive notifications and respond to them in the background by using the iOS application-level
backgroundNotification event. The event is the same 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
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.