Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Next »

Introduction

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.

Notification Types

The following sections describe how iOS may present notifications to users.

Alert Dialog

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.

Badge

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.

Banner Message

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.

Lock Screen

If the device is locked, the notification appears in the lock screen. The user swipes the notification to the right to launch the application.

Notification Center

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 button to clear the notifications.

Sound

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.registerUserNotificationSettings() method to enroll the application in local notification services.  Pass the method a dictionary with the types property set to an array of notification types to use. 

  • Titanium.App.iOS.USER_NOTIFICATION_TYPE_ALERT: allow the application to display an alert or banner message.
  • Titanium.App.iOS.USER_NOTIFICATION_TYPE_BADGE: allow the application to modify the badge value in the application's icon.
  • Titanium.App.iOS.USER_NOTIFICATION_TYPE_NONE: disable application UI notifications.  The application will still be notified of the notification by the notification event.
  • Titanium.App.iOS.USER_NOTIFICATION_TYPE_SOUND: allow the application to play a sound.
Icon

If you are using interactive notifications, the application also needs to register the notification categories you want to use.  Set the categories property of the dictionary passed to the registerUserNotificationSettings() method to an array of notification category objects that the application needs to use.  For more details, see the Create an Interactive Notification section below.

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.

The application can monitor the usernotificationsettings event to know when and which user notification types and categories are registered.

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).
  • date: datetime to send the notification as a JavaScript Date object. If omitted, the notification is sent immediately.
  • repeat: interval to repeat the notification. Values can be: dailyweeklymonthly or yearly.  Default is once.
  • sound: sound file to play relative to the Resources or app/assets directory.
  • 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 notification event.

LockedAlertAnnotated

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 interval property.

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 Titanium.App.iOS.cancelAllLocalNotifications() method.

To cancel a specific notification, the application can either:

  1. Keep a reference to the notification object and call the cancel() method on the object.
  2. 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 id property of the userInfo dictionary passed to the scheduleLocationNotification() method.

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:

  1. Create and configure notification actions
  2. Create notification categories and assign notification actions to them
  3. Register the notification categories
  4. Monitor the backgroundNotification event while the app is the background

The following screen shots 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 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:

  • 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.

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 triggered when the user selects a notification action.  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.

 

 

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.

 



  • No labels